# 模型接入指南（LLM） - 常见问题
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
本文汇总方舟大模型**接入 / 上线过程中的常见问题**（效果、可用性、接入配置、选型四类），每个问题按 现象 → 原因 → 排查思路 → 深度阅读 组织。同类问题也可能被称作"FAQ / 排障指南 / 接入常见问题 / 上线常见问题"。
## 模型效果类问题
### 思考内容没回传，静默影响推理效果
- **现象**：Coding / Agent 场景下多轮工具调用效果随轮数增加而下降；相同 Prompt 在不同实现下任务通过率差异明显；缓存命中率异常。
> **注意**
>
> Seed-Evolving、Seed 2.1 系列及往后模型需重点关注。这些模型返回的是加密思考块，若不回传，模型推理效果会显著下降，且不会有任何 API 报错提示。
- **原因**：Agent 场景是多轮"推理 → 调工具 → 拿结果 → 继续推理"循环。如果不回传思考内容，推理连续性会被打断、多步执行稳定性下降、缓存被破坏成本上升，最终导致模型性能显著下降。
- **排查思路**：
- **选对回传字段**：根据模型和 API 类型，选明文 `reasoning_content` / 加密 `encrypted_content` / Anthropic `signature`。
- **Chat API 整体回传**：将响应中的 assistant message 整体加入下一轮 `messages`，不要按字段挑选重建。
- **Responses API 用托管上下文（推荐）**：使用 `previous_response_id` + `store: true`，服务端自动管理回传。
- **Anthropic 兼容 API 整块回传**：`thinking` 块必须整块回传（`thinking` 文本 + `signature`），保持在 `tool_use` 块之前的原始顺序。
- **遵守加密块关键规则**：
- 必须**原样、完整**回传，任何篡改或截断都会返回 `Invalid signature` 错误。
- 不回传不报错，但静默影响推理效果。
- **思考内容按原始（加密块内）token 计费**，不回传等于已付费但未生效。
- 加密字段优先级高于明文摘要：同时传入时，明文摘要会被忽略。
- 流式响应中 `encrypted_content` 由独立 chunk 下发（思考完成后、正式应答前），流式合并逻辑必须处理该字段。
- 同一模型不同版本可能属于不同类别（如 `doubao-seed-2-0-lite-260215` 是明文，`doubao-seed-2-0-lite-260428` 改为加密块）。**升级模型版本时必须同步检查回传代码**，否则回传失效且不会报错。
- **深度阅读**：
- [Agent 场景模型调用的正确姿势](/docs/agent-model-invocation-practice)：各 API 字段矩阵、明文 / 加密支持模型清单、完整代码示例与流式响应处理规则。
### Harness 关键配置缺失
- **现象**：用 Codex CLI、Claude Code 等工具接入后，模型不思考、不走 Responses API、子任务用错模型，可能导致效果差很多。
- **原因**：三方 Harness 涉及多个模型位、超时、思考等级等环境变量，任一缺失都会导致行为退化。
> **注意**
>
> Agent / Coding 场景不推荐使用 Chat API。Codex 优先使用 Responses API，Claude Code 使用 Anthropic 兼容 API。
- **排查思路**：**对照完整配置示例逐项核查**。完整配置模板已放在 [标准流程 · 接入三方 Harness](/docs/go-live-access-sop#third-party-harness)，常见漏项如下：
- **Claude Code**：
- **Haiku / Sonnet / Opus 三个模型位都要配**：只配 `ANTHROPIC_MODEL` 不够，子任务可能 fallback 到默认模型。
- **HAIKU 位配 lite / mini**：`ANTHROPIC_DEFAULT_HAIKU_MODEL` 建议配 lite / mini 类小尺寸模型，避免端到端延时过长。
- **SUBAGENT 与主模型一致**：`CLAUDE_CODE_SUBAGENT_MODEL` 建议与 `ANTHROPIC_MODEL` 保持一致。
- **Codex**：
- **携带 User-Agent Header**：请求 Header 必须带 `User-Agent`（可取 `codex_appserver` / `codex`），否则报错 `json: unknown field "client_metadata"`。若中台无法修改，可将客户端 `User-Agent` 加入白名单。
- **部分模型移除 reasoning summaries**：`minimax-m2.7` / `kimi-k2.6` / `kimi-k2.7-code` 不支持 `model_supports_reasoning_summaries = true`，接入这些模型时需要移除该配置项。
- **调大最大输出长度**：
- Claude Code 设置 `CLAUDE_CODE_MAX_OUTPUT_TOKENS=128000`。
- Codex 设置 `model_max_output_tokens=128000`。
- **调大客户端超时**：
- Claude Code 设置 `API_TIMEOUT_MS=1800000`。
- Codex 设置 `stream_idle_timeout_ms=1800000`。
- **深度阅读**：
- [标准流程 · 接入三方 Harness](/docs/go-live-access-sop#third-party-harness)：Claude Code / Codex 完整 JSON / TOML 配置示例与说明。
- [接入三方工具](/docs/integrate-third-party-tools)：其他 Harness（Chatbox、Cherry Studio、TRAE 等）的接入示例。
### `max_tokens` 没传或太小，输出被截断
- **现象**：模型回答到一半停了、工具调用的 JSON 参数半截解析失败、Agent Loop 中途断掉。常被误判为模型"不会做"或"不稳定"。
- **原因**：`max_tokens`（Chat API）/ `max_output_tokens`（Responses API）不传时可能使用较小默认值，Agent 场景下思考链 + 工具调用 + 正式回答的输出长度很容易超过。
- **排查思路**：
- **显式传入 max_tokens**：Agent / Coding 场景建议 ≥ 128000。
- **配置 Claude Code 输出上限**：设置环境变量 `CLAUDE_CODE_MAX_OUTPUT_TOKENS=128000`。
- **检查截断标识**：查看响应中的 `finish_reason`（Chat）/ `stop_reason`（Responses），值为 `length` 即被截断。
- **深度阅读**：
- [Agent 场景模型调用的正确姿势](/docs/agent-model-invocation-practice)：输出长度参数配置章节。
### `thinking=auto`，模型未开启深度推理
- **现象**：简单问题回答正常，复杂多步任务（架构设计、多工具编排）效果明显差，模型不做规划直接给答案。
- **原因**：`thinking` 设为 `auto` 时，模型自行判断是否需要深度思考。Agent 场景下模型可能误判任务简单而跳过推理，导致工具选择和参数构造错误率上升。
- **排查思路**：**显式启用深度思考**：Agent / Coding 场景显式设置 `thinking={"type": "enabled"}`，同时 `reasoning_effort` 建议设为 `high` 或以上。
- **深度阅读**：
- [深度思考](/docs/deep-thinking)：深度思考功能的适用范围与配置细节。
### 缓存失效
- **现象**：多轮对话越聊越慢（TTFT 飙升）、成本上升，但没有任何报错。客户往往误以为"模型变慢了"。
- **原因**：Session 内改动采样参数、思考配置、工具定义或系统提示词，都会重置缓存。
- **排查思路**：
- **保持 Session 参数稳定**：同一 Session 内不改动采样参数（`temperature` / `top_p`）、思考配置（`thinking` / `reasoning_effort`）、工具定义（`tools`）、系统提示词。
- **前置公共前缀**：系统提示词与工具定义放在请求最前部。
- **开启显式缓存**：`store: true`（默认即 `true`）+ `caching={"type": "enabled"}`。
- **监控命中率**：观察响应中的 `cached_tokens` 字段。
- **深度阅读**：
- [上下文缓存](/docs/context-cache)：前缀缓存与显式缓存的完整生效条件。
### 低延迟模式非 100% 生效
- **现象**：设了 `service_tier=fast`，但延迟忽快忽慢，有时候和常规模式没区别。
- **原因**：低延迟推理在超出 fast TPM 限流配额、命中 QoS 防护、异常高并发或超长请求时，会自动降级为常规在线推理，降级后请求仍可能成功但延迟回到常规水平。低延迟与常规的限流配额相互独立，需要分别评估。
- **排查思路**：
- **观察 fast 模式指标**：在控制台监控页关注 fast 模式 TPM、降级量（fast → default）和降级比例。
- **按峰值 TPM 评估配额**：而非分钟平均（限流计算周期为 10–15 秒）。
- **控制流量斜率**：流量增长斜率同样受每 3 分钟 20% 的限制。
- **避开长输出请求**：长输出请求不建议使用低延迟模式。
- **深度阅读**：
- [在线推理（低延迟）](/docs/online-inference-low-latency)：自动降级触发条件（限流限制、斜率限制、攻击 / 长请求防护）与限流配额规则。
## 服务可用性与稳定性问题
### 429 分不清配额超限还是突发流量限流
- **现象**：收到 429 错误，客户一律以为"额度不够"，去提工单扩容，但实际可能是突发流量保护，扩容解决不了问题。
- **原因**：方舟对 429 有两种不同触发机制，`error.code` 字段可以直接区分。
- **排查思路**：**先看 error.code 定位机制**：拿到 429 后先看响应体里的 `error.code`：
| 机制 | 触发条件 | 典型错误码 | 解法 |
| --- | --- | --- | --- |
| 配额限流 | RPM / TPM 超过配额 | `ModelAccountRpmRateLimitExceeded`、`ModelAccountTpmRateLimitExceeded` | 调大接入点限流 / 提工单扩容 / 降速 |
| 突发保护 | 流量增长过快或资源紧张，配额可能没用完 | `ServerOverloaded`（seed-1.8 及之前）、`RequestBurstTooFast`（seed-2.0 及之后） | 控斜率 + 排队 + 重试，扩容无效 |
- **深度阅读**：
- [错误码](/docs/error-codes)：完整错误码含义。
- [突发流量处理最佳实践](/docs/traffic-burst-handling-best-practices)：突发保护的处理策略。
### 突发流量导致 429，扩容无效
- **现象**：业务刚上线或定时任务集中触发时大量 429（`ServerOverloaded` / `RequestBurstTooFast`），但平峰期正常。
- **原因**：方舟对流量增长斜率有保护，建议 Token 用量增长速率控制在每 3 分钟 20% 以内。平台遇到突发会快速扩容（分钟级），但客户端如果猛打流量，扩容来不及就会熔断。
- **排查思路**：**按策略控制爬坡**：使用排队 Header（首选）、QPS 爬坡器、削峰填谷或跨模型分流。核心动作对比见 [标准流程 · 阶段二：突发流量爬坡](/docs/go-live-access-sop#traffic-burst-strategy)。
- **深度阅读**：
- [突发流量处理最佳实践](/docs/traffic-burst-handling-best-practices)：四种策略的完整参数、代码示例与选型建议。
### 客户端超时不够导致断连
- **现象**：调用深度思考模型时频繁超时报错；非流式模式下长时间无响应后断开连接，任务未完成且已产生 token 用量费用；叠加排队 Header 后超时更易触发。
- **原因**：
- 深度思考模型使用思维链输出内容，回复篇幅更长、生成速率更慢，默认超时（通常 30s–60s）不足以覆盖完整生成时间。
- 开启 thinking summary 能力的模型，包间延迟较高。
- 叠加排队 Header（`X-Ark-Max-Wait-Timeout-Ms`）后，客户端超时需同步叠加。
- **排查思路**：
- **优先改为流式输出**：使用 `stream=true` 分块即时返回内容，维持连接活性，规避长任务超时。
- **调大非流式超时**：客户端超时 = 模型生成时间 + 排队时间，Agent 场景建议设 30 分钟以上；同时留意 TCP Keep-Alive 设置，避免防火墙 / 路由器主动断连。
- **Go SDK 强制调大超时**：无论是否使用流式输出，均需将 SDK 超时参数设置为 30 分钟以上。
- **同步放大 Claude Code 超时**：设置 `CLAUDE_CODE_MAX_OUTPUT_TOKENS=128000` 后输出变长，`timeout` 也要相应调大。
- **深度阅读**：
- [深度思考](/docs/deep-thinking)：深度思考模型的输出时长与包间延迟说明。
- [突发流量处理最佳实践](/docs/traffic-burst-handling-best-practices)：排队 Header 与客户端超时的配套关系。
### 同模型多 Endpoint / 多账号分流无效
- **现象**：客户为了规避限流，创建多个 Endpoint 或用多个账号轮询调用同一个模型，结果仍然 429。
- **原因**：方舟模型限流是同主账号下同模型共享的，不区分版本。可以对自定义推理接入点单独限流，但同一模型的所有 Endpoint 和账号底层共享同一个资源池，流量最终汇聚。
- **排查思路**：
- **改用跨模型分流**：如同时调用 seed-2.1-pro 和 seed-2.0-pro，不同模型资源池独立。
- **提工单扩容配额**：单模型账号级配额提升。
- **配合排队 Header 与 QPS 爬坡**：控制发送速率。
- **深度阅读**：
- [突发流量处理最佳实践](/docs/traffic-burst-handling-best-practices)：跨模型分流的适用场景与配置方式。
### 冷启动首请求报错
- **现象**：长时间没有流量的 Endpoint，突然调用时报 `ServerOverloaded` / `InflightBatchsizeExceeded`，但过一会儿再调就正常了。
- **原因**：
- `ServerOverloaded`：长时间无流量时服务缩容，第一个请求撞上扩容过程。
- `InflightBatchsizeExceeded`：服务过载熔断，限制该时段内有突发请求、新上量的客户；流量平稳的客户不受影响。
- **排查思路**：
- **携带排队 Header**：请求加 `X-Ark-Max-Wait-Timeout-Ms`，给服务端扩容留出时间。
- **客户端爬坡预热**：从低 QPS 开始逐步提升，不要一上来就打满。
- **错峰触发定时任务**：避免集中冷启动。
- **申请提额**（仅限 `InflightBatchsizeExceeded`）：非默认 TPM 能够豁免系统熔断。
- **深度阅读**：
- [突发流量处理最佳实践](/docs/traffic-burst-handling-best-practices)：冷启动预热与排队策略的组合用法。
### 代理导致连接失败
- **现象**：调用方舟 API 报 `ArkAPIConnectionError` 域名连接超时，或 `httpx.InvalidURL: Invalid port ':'`，客户以为方舟服务不可用。
- **原因**：客户环境配置了 HTTP / HTTPS 代理（公司网络常见），请求走了代理导致无法连接方舟域名；或代理 URL 格式不兼容（如 `socks5h`）。
- **排查思路**：**禁用代理或加白名单**：
```python
# 禁用代理
client = Ark(
api_key=os.environ.get("ARK_API_KEY"),
base_url="https://ark.cn-beijing.volces.com/api/v3",
http_client=httpx.Client(proxies={"http://": None, "https://": None}),
)
```
或设置环境变量 `no_proxy="ark.cn-beijing.volces.com"`。先 `ping ark.cn-beijing.volces.com` 确认网络连通性；Linux 环境检查 `/etc/resolv.conf` DNS 配置。
### 图片输入失败
- **现象**：视觉模型调用报 `InvalidParameter`，图片 URL 明明可以访问。
- **原因**：方舟服务端下载图片的限制：默认超时 5 秒；必须公网可访问；Content-Type 需与实际格式匹配；建议压缩至 100kB 以下。
- **排查思路**：**改用同区域 TOS 或 Base64**：将图片转存到火山引擎 TOS（同区域内网传输快），或压缩后使用 Base64 传入。
### 流式与非流式选择
- **现象**：非流式模式在长任务下频繁超时；流式模式拼接完成后 `usage` 拿不到。
- **原因**：Chat API 通过 `stream` 参数控制返回方式，两种模式的返回机制、超时风险、`usage` 默认行为均不同。
- **排查思路**：
- **选非流式**：适合结构化结果、Function Calling 参数解析、后端批处理。一次性返回完整响应体，`usage` 默认包含；缺点是长任务易超时。
- **选流式**：适合对话交互、长文本 / 深度思考生成。按 SSE 逐块返回，TTFT 低，可规避长任务超时；`usage` 默认不返回，需设 `stream_options={"include_usage": true}`。
- **深度阅读**：
- [流式输出](/docs/streaming-output)：流式响应的完整拼接逻辑与最佳实践。
## 接入配置问题
### `model` 字段建议使用 Endpoint ID 而非 Model ID
- **现象**：生产环境使用 Model ID 调用，难以做限流配置、版本切换和监控。
- **原因**：Endpoint ID（形如 `ep-********`）可以对模型调用做更精细化的管理。
- **排查思路**：
- **快速验证用 Model ID**：新用户可以直接用 Model ID 或预置接入点 Endpoint ID。
- **生产环境用 Endpoint ID**：创建自定义推理接入点，用 Endpoint ID 调用，便于做限流配置、版本切换和监控。
- **深度阅读**：
- [创建推理接入点](/docs/create-endpoint-api)：控制台入口与创建流程。
### 不同协议 Base URL 不同
- **现象**：Claude Code 配了 `/api/v3` 的 Base URL 报奇怪的错；OpenAI 兼容工具配了 `/api/compatible` 也报错。
- **原因**：方舟提供两套兼容协议，Base URL 不同。
- **排查思路**：
- **配 OpenAI 兼容 Base URL**：`https://ark.cn-beijing.volces.com/api/v3`，适用 Codex CLI、Chatbox、Cherry Studio、OpenCode、TRAE、Cursor、Cline 等。
- **配 Anthropic 兼容 Base URL**：`https://ark.cn-beijing.volces.com/api/compatible`，适用 Claude Code 等 Anthropic 生态工具。
- **深度阅读**：
- [接入三方工具](/docs/integrate-third-party-tools)：各工具的完整 Base URL 与 Header 配置。
## 选型注意事项
### Responses API 不支持保障包 / 精调模型 / 智能路由
- **现象**：新业务按推荐上了 Responses API，后续要接 TPM 保障包或精调模型时发现不支持，得回退 Chat API，返工成本高。
- **原因**：Responses API 目前不支持以下功能：TPM 保障包（已几乎不再售卖）、精调后模型的在线推理、智能模型路由、在线推理服务的模型版本平滑切换。
- **排查思路**：
- **新业务优先 Responses API**：如果明确不需要 TPM 保障包 / 精调 / 智能路由，选它（自动上下文管理、内置工具、缓存降本）。
- **有历史依赖继续 Chat API**：如果已有或计划使用精调模型、保障包，继续用 Chat API。
- **深度阅读**：
- [迁移至 Responses API](/docs/responses-api-migration)：Responses API 与 Chat API 的功能矩阵与迁移指南。