Question 1

如何禁用 LiveKit Agents 的 EOT 权重预加载，以减少 worker 的内存占用？

Accepted Answer

升级到包含 PR #7580 的 LiveKit Agents 版本，然后使用 `LIVEKIT_AGENTS_PRELOAD_EOT=0` 启动 worker。可接受的禁用值为 `0`、`false`、`no` 和 `off`。

临时 shell 启动方式：
```bash
export LIVEKIT_AGENTS_PRELOAD_EOT=0
python your_worker.py
```

对于 systemd worker，添加：
```ini
[Service]
Environment=LIVEKIT_AGENTS_PRELOAD_EOT=0
```

这会跳过约 240 MB 的 end-of-turn 模型预加载，同时保留轻量级的 VAD 预加载。如果之后实际使用了本地 `TurnDetector`，其权重将在首次使用时延迟加载。在 Linux `forkserver` 下，EOT 预加载默认保持启用状态。如果一台主机上运行多个 worker，也可以使用单个 `AgentServer` 并设置更大的 `num_idle_processes`，从而共享一份副本，而不是每个 worker 各自加载一次。

Question 2

如何修复 LiveKit Agents THREAD 执行器在关闭时挂起并提示 'job did not ack shutdown in time' 的问题？

Accepted Answer

将 `livekit-agents` 升级到 **1.8.3 或更高版本**。此关闭竞态问题已由 PR #7225 修复；包括 1.8.1 在内的版本，当空闲的预热 THREAD 运行器在其关闭确认被读取之前退出时，可能会发生挂起。

```bash
pip install --upgrade 'livekit-agents>=1.8.3'
```

如果使用 uv：

```bash
uv add 'livekit-agents>=1.8.3'
```

然后重启 worker，并在空闲运行器初始化完成后发送 SIGTERM/Ctrl+C。worker 应当能够迅速关闭，且不再反复出现 `job did not ack shutdown in time` 错误。

如果暂时无法升级，请使用 `JobExecutorType.PROCESS`，它不会出现此挂起问题。发送第二次信号只会强制终止进程，并不是一种优雅的变通方法。

Question 3

使用 LiveKit Agents 搭配 JobExecutorType.THREAD 时，如何修复 "ResourceWarning: unclosed event loop"？

Accepted Answer

此问题出现在受影响的版本中，例如 `livekit-agents==1.8.4`：`_ProcClient.run()` 创建了 asyncio 事件循环，但没有取消待处理任务、关闭异步生成器、重置线程事件循环，也没有关闭该循环。

**首选修复方案：** 将 `livekit-agents` 升级到包含 PR `fix(ipc): close the job loop when the runner exits` 的版本（该 PR 修复了 issue #7629）。

如果无法立即升级，请修改 `_ProcClient.run()` 中的 `finally` 代码块，使其执行与 `asyncio.run()` 相同的关闭序列：

```python
finally:
    loop_monitor.stop_monitoring(loop)
    try:
        pending = [t for t in asyncio.all_tasks(loop) if not t.done()]
        for task in pending:
            task.cancel()
        if pending:
            loop.run_until_complete(
                asyncio.gather(*pending, return_exceptions=True)
            )
        loop.run_until_complete(loop.shutdown_asyncgens())
        loop.run_until_complete(loop.shutdown_default_executor())
    finally:
        asyncio.set_event_loop(None)
        loop.close()
```

作为临时解决方案，请使用进程隔离而不是线程：

```python
server = AgentServer(job_executor_type=JobExecutorType.PROCESS)
```

修复后，已完成的 job 循环应报告 `is_closed() == True`，并且 Python 不应再发出 `ResourceWarning: unclosed event loop`。

Question 4

为什么在 LiveKit Agents 中 Muse STT 的转录文本和 end-of-turn 事件会出现延迟？如何解决音频延迟问题？

Accepted Answer

根本原因：在 `SpeechStream._send_audio`（livekit-plugins-meta）中，节拍时钟（`pacing_origin`）是在第一个数据包被*发送*时启动的，而不是在流启动时。由于 `_run` 会先等待 `_connect_ws()`，在 Muse websocket 连接期间排队的任何音频帧都会产生永久性偏移——此后整个流中的每个数据包都会晚发送相当于连接时长的时间（例如，300 ms 的连接时间 ≈ 221 ms 的恒定延迟），因为节拍发送永远不会快于实时，积压的数据也永远无法追上。这会将转录结果和回合结束事件延迟相同的时长。

修复（PR #7890）：在流开始运行时启动节拍时钟，而不是在首次发送时。一旦 socket 就绪，缓冲的积压数据会立即被刷新，后续数据包则像以前一样按实时进行节拍控制。

在修补版本发布前的临时解决方案：monkey-patch `_send_audio`，使其在 `_input_ch` 仍有排队帧时跳过节拍休眠（仅在缓冲区排空后才休眠）。已确认受影响的版本：livekit-agents==1.8.6、livekit-plugins-meta==1.8.6 搭配 `muse-voice-transcribe-1.0`。

Question 5

为什么 LiveKit Agents 会在最终转录文本仅添加阿拉伯语、CJK、天城文或乌尔都语标点符号时,使预生成(preemptive generation)失效?

Accepted Answer

受影响的版本：livekit-agents 1.8.3 和 main @ 57b3227。`_transcripts_equivalent()` 调用了 `split_words(..., ignore_punctuation=True)`，但 `livekit/agents/tokenize/_basic_word.py` 中的标点符号移除列表仅涵盖 ASCII 字符。因此，阿拉伯语的 `، ؛ ؟`、乌尔都语的 `۔`、天城文的 `।` 以及全角 CJK 的 `，。` 仍然附着在单词上，导致最终转录文本看起来不一致，并触发 `preemptive generation invalidated ... because the transcript ... changed`。

修复分词器，使其在现有 ASCII 标点符号之外，同时移除所有 Unicode 标点符号类别（`P*`）：

```python
import unicodedata

def _is_punctuation(char: str) -> bool:
    return (
        char in tokenize.tokenizer.PUNCTUATIONS
        or unicodedata.category(char).startswith("P")
    )
```

在 `_basic_word.py` 中所有 `ignore_punctuation=True` 过滤字符的位置使用此检查。这样可以保留诸如 `$` 和 `+` 这类类别为 `S` 的符号，以及类别为 `Mn` 的阿拉伯语变音符号。

使用以下代码验证：

```python
from livekit.agents.voice.agent_activity import _transcripts_equivalent

assert _transcripts_equivalent("مرحبا كيف حالك", "مرحبا، كيف حالك؟")
assert _transcripts_equivalent("你好 我很好", "你好，我很好。")
assert _transcripts_equivalent("आप कैसे हैं", "आप कैसे हैं।")
```

重新构建或重新安装已打补丁的软件包。上游修复发布后，使用 `pip install -U livekit-agents` 进行升级。

agents

项目简介

README 预览

常见问题 (5)

同类型项目

tensorflow

superpowers

everything-claude-code

flutter