1. VideoAgent 第一次跑视频问答就报 APIConnectionError？先查 LLM_BASE_URL 这一行

VideoAgent 第一次跑视频问答就报 APIConnectionError？问题常常不在分段和编排，而在 .env 里的 LLM_BASE_URL。本文的做法是：先去 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=videoagent_llm_base_url 拿一个 Key，再把 Base URL 写成 https://taotoken.net/api，让整条问答链路的语言模型调用改道。

VideoAgent 是港科大 HKUDS 实验室开源的一套视频智能体框架，把「看视频、剪视频、玩视频」三件事收进一个聊天入口。理解层负责语义搜索、长视频问答、自动摘要；剪辑层负责按语义裁剪、字幕转场配音包装、长视频浓缩成精华版；二创层更出圈，视频转播客、名场面截表情包、TTS 配音与音色转换、喜剧风格改编都能走。它的问答不是把整段视频塞给模型，而是先把画面、语音、字幕切成秒级片段并编码成语义向量，检索命中后再交给语言模型组织答案。

所以你在终端看到的每一次「嘉宾在第几分钟提到成本问题」，背后至少有一次语言模型调用，而这次调用的目标地址就是 LLM_BASE_URL。这条链路一旦指错，表现千奇百怪：有的连不上，有的鉴权失败，有的模型名对不上直接 404，还有的能答但上下文被截断、时间戳全乱。下面按「报错 → 变量 → 请求」三步走，先把视频问答跑通一次，再谈剪辑和二创。

2. 改 Base URL 之前，先认清 VideoAgent 问答链路上的四类报错

很多人以为 VideoAgent 跑不起来是安装问题，其实装完跑不动，绝大多数集中在语言模型这一跳。把报错归类，能省掉大量瞎试时间。

第一类：连接类。 典型输出是 openai.APIConnectionError、Connection timed out、SSLError，或者 Failed to resolve host。根因是 LLM_BASE_URL 指向的入口在你当前网络下不可达，或者写成了 https://xxx 但实际需要额外的路径段。这类报错最容易误判成「代码有 bug」，其实只是地址不对。

第二类：鉴权类。 典型输出是 Error code: 401 - invalid_api_key、Unauthorized、Missing bearer token。根因通常是三个：Key 没填、Key 前后带了空格或引号、把 Key 写进了 OPENAI_API_KEY 但代码读的是 LLM_API_KEY。VideoAgent 的不同 fork 在变量名上并不完全统一，这一点后面会用对照表解决。

第三类：模型与上下文类。 典型输出是 model not found、The model does not exist、context_length_exceeded。前两种是模型 id 写错，第三种是检索回来的片段太长，超出了所选模型的上下文上限。长视频问答特别容易撞上第三种，因为一小时讲座的字幕转写轻松上万字。

第四类：成本与限流类。 典型输出是 429 Too Many Requests、insufficient_quota，或者没报错但账单涨得比预期快。VideoAgent 一次问答会触发一次（有时多次）语言模型调用，如果每次都把全量字幕喂进去，token 消耗会线性放大。

这四类里，只有第四类是「策略问题」，前三类都能靠正确填写 LLM_BASE_URL 和配套变量解决。这也是本文把变量对照放在第一步的原因。

3. 环境变量对照表：VideoAgent 里到底哪几个键要动

VideoAgent 仓库通常带一份 .env.example，不同版本键名略有差异。下面这张表是实践中最常见的映射关系，最终请以你本地 clone 下来的 .env.example 为准，不要照抄一份不确定的变量名。

变量名	作用	改前的常见值	改后填什么
LLM_BASE_URL	问答与编排所用语言模型的 API 入口，最关键的变量	指向第三方或官方默认地址	https://taotoken.net/api
LLM_API_KEY	与上面 Base URL 配对的密钥	空、占位或旧 Key	YOUR_API_KEY
LLM_MODEL_NAME	主问答模型 id（有的版本叫 LLM_MODEL）	某个具体模型名	控制台里实际可用的模型 id
OPENAI_API_BASE	走 OpenAI SDK 时生效的入口（部分版本使用）	空或旧地址	https://taotoken.net/api
OPENAI_API_KEY	走 OpenAI SDK 时生效的密钥	空或旧 Key	YOUR_API_KEY
EMBEDDING_BASE_URL	语义索引向量化的入口（如果你的版本单独拆开）	空	视仓库而定，可先留空用本地向量模型
ASR_MODEL / WHISPER_*	语音转写，决定字幕质量	本地模型路径	保持本地 Whisper 即可

有几个坑必须提前说清楚：

• 不要把 ANTHROPIC_* 系列变量套到 VideoAgent 的 OpenAI 兼容链路上。 这两套是不同协议，写错会直接 400。
• 不要把 Base URL 写成带 /chat/completions 的完整地址。 OpenAI 兼容客户端会自己拼路径，你只需要给到 https://taotoken.net/api。
• .env 里的值不要加引号。 LLM_BASE_URL="https://taotoken.net/api" 在某些解析器里会把引号当值的一部分，导致拼接出非法 URL。
• 改完必须重启进程。 .env 一般只在启动时读取一次，改了不重启等于没改。

把 .env 写成这样，是最小可用的形态：

# .env —— 放在 VideoAgent 仓库根目录
# 语言模型入口：本文的核心改动
LLM_BASE_URL=https://taotoken.net/api
LLM_API_KEY=YOUR_API_KEY
LLM_MODEL_NAME=YOUR_MODEL_ID

# 兼容部分走 OpenAI SDK 的模块
OPENAI_API_BASE=https://taotoken.net/api
OPENAI_API_KEY=YOUR_API_KEY

# 本地能力保持默认，先不动
ASR_MODEL=small

如果你不想改仓库里的 .env（多人协作时容易被覆盖），也可以在启动前用 shell 环境变量覆盖，效果一致：

export LLM_BASE_URL="https://taotoken.net/api"
export LLM_API_KEY="YOUR_API_KEY"
export LLM_MODEL_NAME="YOUR_MODEL_ID"

4. 从拿 Key 到重启服务：把 LLM_BASE_URL 指到 TaoToken 的五步

第一步：拿 Key。 打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=videoagent_getkey ，完成注册后进控制台创建 API Key。建议单独建一个叫 videoagent 的 Key，方便后面按项目看用量、也能随时吊销。创建入口在 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=videoagent_key_create 。

第二步：确认你要用哪个模型。 在控制台里挑一个支持长上下文的模型 id，复制下来。长视频问答对上下文窗口要求不低，一个 45 分钟讲座的检索片段合集动辄几千到上万 token，别选窗口太小的模型。

第三步：写进 .env。 按上一节的对照表填，重点是 LLM_BASE_URL=https://taotoken.net/api 这一行。

第四步：先不启动 VideoAgent，单独验证入口通不通。 一条 curl 就够：

curl -sS -o /dev/null -w "HTTP %{http_code}\n" \
  https://taotoken.net/api/models \
  -H "Authorization: Bearer YOUR_API_KEY"

返回 HTTP 200，说明地址和 Key 都没问题；返回 401 是 Key 的问题，返回 404 大概率是路径段写多或写少了。这一步能把网络问题和 VideoAgent 代码问题彻底切开，是排障里最值钱的一分钟。

第五步：重启 VideoAgent 进程，再跑一次问答。 如果你是用 uvicorn、streamlit 或 python run.py 起服务，先 Ctrl+C 彻底停掉，再重新拉起。热重载不一定会重新读 .env。

跑通之后，建议把这次可用的配置固化下来，写进项目 README 或者一个 .env.local.example，下次换机器直接抄，不用再回忆哪几个变量动过。

5. 一次可复现的视频问答请求：从片段索引到带时间戳的答案

VideoAgent 的问答链路，本质是「检索 + 生成」两段式。检索由它自己的向量索引完成，生成那一段就是一次普通的 chat 调用。所以你可以先绕开框架，用一段最小的 Python 请求，验证「检索结果 + 问题」这组输入能不能拿到带时间戳的答案。这一步通了，VideoAgent 里的问答基本不会再有地址层面的问题。

# qa_smoke_test.py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://taotoken.net/api",
)

# 真实场景里，这段内容由 VideoAgent 的向量检索产出
retrieved_segments = """
[00:12:30 - 00:13:05] 主持人提问：这套方案的部署成本大概在什么量级？
[00:13:06 - 00:14:20] 嘉宾回答：早期我们按单机测算，主要开销集中在推理卡的租用上……
[00:27:41 - 00:28:10] 嘉宾补充：如果按年度摊，服务器以外的成本占比不到三成。
"""

question = "嘉宾第一次正面提到成本问题是在第几分钟？请给出时间戳并引用原句。"

resp = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[
        {
            "role": "system",
            "content": "你是视频问答模块。只依据给定的带时间戳片段回答，"
                       "答案必须包含时间戳；片段中没有的信息，直接说没有检索到。",
        },
        {
            "role": "user",
            "content": f"视频片段检索结果：\n{retrieved_segments}\n\n问题：{question}",
        },
    ],
    temperature=0.2,
    max_tokens=512,
)

print(resp.choices[0].message.content)

预期输出应该类似：

嘉宾第一次正面提到成本问题是在 00:12:30，主持人提问「这套方案的部署成本大概在什么量级？」，
嘉宾在 00:13:06 开始回答，提到主要开销集中在推理卡的租用上。

这段代码有三个细节值得保留：temperature 调低到 0.2，减少时间戳被模型「改写成大概」的概率；system prompt 里明确要求「没有检索到就说没有」，避免长视频问答最常见的幻觉；输入必须带时间戳，否则模型只能回「视频里提到过」这种没有信息量的答案。

同一件事也可以用 curl 验证，适合放进 CI 或者一键脚本：

curl -sS https://taotoken.net/api/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "temperature": 0.2,
    "max_tokens": 512,
    "messages": [
      {"role": "system", "content": "只依据给定片段回答，必须给时间戳。"},
      {"role": "user", "content": "[00:13:06] 嘉宾回答：主要开销集中在推理卡租用上。问题：成本问题在第几分钟被提到？"}
    ]
  }'

拿到结构化答案之后，再回到 VideoAgent 界面提同一个问题。如果框架里答得不对，但这段最小请求是对的，那问题就落在检索质量上（切片粒度、embedding 模型、top-k 取值），而不是 Base URL 配置。这个判断能帮你省下大量「反复怀疑 Key 填错」的时间。

6. 401 / 404 / 429 / 超时：VideoAgent 接 TaoToken 的排障速查

把常见症状和动作列成一张表，出问题时按顺序对：

症状	最可能的原因	立刻要做的动作
401 invalid_api_key	Key 未填、带空格、或读写不一致	检查 LLM_API_KEY 与 OPENAI_API_KEY 是否都有值；重跑 curl 验证
404 model not found	模型 id 写错，或 Base URL 多带了路径	模型 id 从控制台复制；确认 Base URL 是 https://taotoken.net/api
404 Not Found（无具体信息）	Base URL 写成了 /v1 或带 /chat/completions	改回 https://taotoken.net/api
429 Too Many Requests	并发过高或触发限流	降低并发，问答请求加指数退避重试
请求长时间无响应	单次输入片段过多	缩小 top-k，先取 3～5 个最相关片段
context_length_exceeded	检索片段总长超出模型窗口	对片段做二次摘要，或换更大窗口的模型
改完没生效	进程没重启、.env 没被加载	彻底停进程重启；确认启动目录是仓库根目录

其中「改完没生效」这一条最容易被忽略。很多人改完 .env 看到服务还在跑，以为热重载生效了，结果一直在测旧配置。判断方法很简单：临时把 LLM_API_KEY 改成一个明显的错值，重启后如果报 401，说明 .env 确实被读到了，再改回正确值。

另外提醒一句，所有验证命令都在你自己的本地终端执行，不要把它包装成服务端自动任务。密钥只放在本机环境变量里，别提交进 Git。

7. 顺手打通 Claude Code、Codex 与 CC Switch 的供应商配置

既然已经在 TaoToken 上有了 Key，VideoAgent 之外的工具也可以一起接上，省得在不同供应商之间来回切。这里要特别注意：Claude Code 用 ANTHROPIC_* 一套，Codex 用 config.toml 一套，两套不能混用。

Claude Code：写 settings.json。 在项目或用户级 settings.json 里配置环境变量：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://taotoken.net/api",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_MODEL": "YOUR_CLAUDE_MODEL_ID"
  }
}

改完重启 Claude Code 会话。想确认是否生效，可以让它读一个本地文件、做一次小改动，观察请求是否正常返回。更完整的接入说明在 https://taotoken.net/doc/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=videoagent_cc_doc 。

Codex：写 config.toml。 注意这里用的是 TOML，不是 ANTHROPIC_*：

model = "YOUR_CODEX_MODEL_ID"
model_provider = "taotoken"

[model_providers.taotoken]
name = "TaoToken"
base_url = "https://taotoken.net/api"
env_key = "TAOTOKEN_API_KEY"
wire_api = "chat"

配套在环境变量里设置 TAOTOKEN_API_KEY=YOUR_API_KEY。把 ANTHROPIC_AUTH_TOKEN 填到 Codex 里是无效配置，这一点在排障时经常被搞混。

CC Switch：三件套。 如果你用 CC Switch 管理多套供应商配置，需要填的就是三个字段：

• Base URL：https://taotoken.net/api
• API Key：YOUR_API_KEY
• Model：控制台里实际可用的模型 id

填完保存，切换过去重启终端即可。三件套里最容易错的是 Base URL 带了多余路径，记住只到 /api 就够了。

8. 长视频问答的 Token 账：钱花在哪，怎么省

VideoAgent 的问答链路里，token 消耗主要发生在三个地方。

第一是语音转写。 如果你用本地 Whisper，这部分不产生 API 费用，只吃本机算力。一小时视频用 small 模型转写，普通笔记本大概几分钟到十几分钟。

第二是画面语义编码。 如果启用了多模态模型描述关键帧，这部分会按图片 token 计费，长视频的帧数量可能很可观。实践中可以先只用字幕做检索，效果不够再开画面编码。

第三是问答生成。 这是最可控也最容易失控的一段。一次问答的输入 = 检索命中的片段集合 + 问题 + system prompt。如果 top-k 取 20，每个片段 500 字，一小时讲座的问答单次输入就能到上万 token。把 top-k 压到 3～5，输入能降到几分之一。

几条实测有效的节省策略：

• 给片段加时间戳再喂。 模型的输出质量提升明显，同时你能一眼看出它有没有胡编时间。
• 对长片段做两阶段摘要。 先用小模型把每个片段压成两三句话，再拿摘要去检索和生成，总输入能显著下降。
• 问答结果做本地缓存。 同一个视频被问「嘉宾什么时候提到成本」这类问题，第二次直接命中缓存，不用再调模型。
• 把索引和问答拆到不同模型。 索引相关的小任务用便宜模型，最终答案组织用能力强的模型。

如果你的使用频率不低，可以看一眼 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=videoagent_plan 里的方案，按额度算通常比零散调用更划算。另外，先在 https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=videoagent_chat 里试几个候选模型，对比同一段视频问答的质量和耗时，再决定主模型，比直接上手就配最强的模型更省钱。

9. 把问答跑通之后，下一步该做什么

回到最初那个报错。VideoAgent 视频问答跑不通，大多数时候不是框架本身的问题，而是语言模型这一跳的配置问题：LLM_BASE_URL 指错、Key 没读到、模型 id 对不上、片段太长超窗口。按本文的顺序——先归类报错，再核对环境变量对照表，然后用一次最小请求验证 Base URL 和 Key，最后回到框架重启验证——基本能覆盖 90% 的首次运行故障。

跑通一次问答之后，建议按这个顺序继续：先用同一个视频问三个不同类型的问题（时间定位、内容归纳、跨片段对比），确认检索和生成都稳定；再把 top-k 和模型调到你满意的性价比点；最后才去折腾剪辑和二创模块，因为那两个模块同样依赖这套语言模型配置，底层不稳，上层只会更难排查。

需要动手的话，路径是这样的：

1. 先试模型对话，看看哪个模型答长视频问答更稳：https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=videoagent_cta_chat
2. 用量上来后看 Coding Plan 是否更适合你的节奏：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=videoagent_cta_plan
3. 创建项目专用的 API Key，方便单独看用量和吊销：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=videoagent_cta_key
4. 如果你同时用 Claude Code，按文档把供应商一次配好：https://taotoken.net/doc/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=videoagent_cta_doc

LLM_BASE_URL=https://taotoken.net/api 这一行改完，重启进程，再问一次那个「第几分钟提到成本」的问题。如果这次返回了带时间戳的答案，VideoAgent 的问答链路就算真正跑通了。