面向 AI 助手：本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/go-live-faq.md，全部文档索引见 https://ark.volcengine.com/llms.txt。

模型接入指南（LLM） - 常见问题

本文汇总方舟大模型接入 / 上线过程中的常见问题（效果、可用性、接入配置、选型四类），每个问题按 现象 → 原因 → 排查思路 → 深度阅读 组织。同类问题也可能被称作"FAQ / 排障指南 / 接入常见问题 / 上线常见问题"。

模型效果类问题#

思考内容没回传，静默影响推理效果#

  • 现象：Coding / Agent 场景下多轮工具调用效果随轮数增加而下降；相同 Prompt 在不同实现下任务通过率差异明显；缓存命中率异常。
  • 原因：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 改为加密块）。升级模型版本时必须同步检查回传代码，否则回传失效且不会报错。
  • 深度阅读：

Harness 关键配置缺失#

  • 现象：用 Codex CLI、Claude Code 等工具接入后，模型不思考、不走 Responses API、子任务用错模型，可能导致效果差很多。
  • 原因：三方 Harness 涉及多个模型位、超时、思考等级等环境变量，任一缺失都会导致行为退化。
  • 排查思路：对照完整配置示例逐项核查。完整配置模板已放在 标准流程 · 接入三方 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。
  • 深度阅读：

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 即被截断。
  • 深度阅读：

thinking=auto，模型未开启深度推理#

  • 现象：简单问题回答正常，复杂多步任务（架构设计、多工具编排）效果明显差，模型不做规划直接给答案。
  • 原因：thinking 设为 auto 时，模型自行判断是否需要深度思考。Agent 场景下模型可能误判任务简单而跳过推理，导致工具选择和参数构造错误率上升。
  • 排查思路：显式启用深度思考：Agent / Coding 场景显式设置 thinking={"type": "enabled"}，同时 reasoning_effort 建议设为 high 或以上。
  • 深度阅读：
    • 深度思考：深度思考功能的适用范围与配置细节。

缓存失效#

  • 现象：多轮对话越聊越慢（TTFT 飙升）、成本上升，但没有任何报错。客户往往误以为"模型变慢了"。
  • 原因：Session 内改动采样参数、思考配置、工具定义或系统提示词，都会重置缓存。
  • 排查思路：
    • 保持 Session 参数稳定：同一 Session 内不改动采样参数（temperature / top_p）、思考配置（thinking / reasoning_effort）、工具定义（tools）、系统提示词。
    • 前置公共前缀：系统提示词与工具定义放在请求最前部。
    • 开启显式缓存：store: true（默认即 true）+ caching={"type": "enabled"}。
    • 监控命中率：观察响应中的 cached_tokens 字段。
  • 深度阅读：

低延迟模式非 100% 生效#

  • 现象：设了 service_tier=fast，但延迟忽快忽慢，有时候和常规模式没区别。
  • 原因：低延迟推理在超出 fast TPM 限流配额、命中 QoS 防护、异常高并发或超长请求时，会自动降级为常规在线推理，降级后请求仍可能成功但延迟回到常规水平。低延迟与常规的限流配额相互独立，需要分别评估。
  • 排查思路：
    • 观察 fast 模式指标：在控制台监控页关注 fast 模式 TPM、降级量（fast → default）和降级比例。
    • 按峰值 TPM 评估配额：而非分钟平均（限流计算周期为 10–15 秒）。
    • 控制流量斜率：流量增长斜率同样受每 3 分钟 20% 的限制。
    • 避开长输出请求：长输出请求不建议使用低延迟模式。
  • 深度阅读：
    • 在线推理（低延迟）：自动降级触发条件（限流限制、斜率限制、攻击 / 长请求防护）与限流配额规则。

服务可用性与稳定性问题#

429 分不清配额超限还是突发流量限流#

  • 现象：收到 429 错误，客户一律以为"额度不够"，去提工单扩容，但实际可能是突发流量保护，扩容解决不了问题。
  • 原因：方舟对 429 有两种不同触发机制，error.code 字段可以直接区分。
  • 排查思路：先看 error.code 定位机制：拿到 429 后先看响应体里的 error.code：

机制 触发条件 典型错误码 解法
配额限流 RPM / TPM 超过配额 ModelAccountRpmRateLimitExceeded、ModelAccountTpmRateLimitExceeded 调大接入点限流 / 提工单扩容 / 降速
突发保护 流量增长过快或资源紧张，配额可能没用完 ServerOverloaded（seed-1.8 及之前）、RequestBurstTooFast（seed-2.0 及之后） 控斜率 + 排队 + 重试，扩容无效

突发流量导致 429，扩容无效#

  • 现象：业务刚上线或定时任务集中触发时大量 429（ServerOverloaded / RequestBurstTooFast），但平峰期正常。
  • 原因：方舟对流量增长斜率有保护，建议 Token 用量增长速率控制在每 3 分钟 20% 以内。平台遇到突发会快速扩容（分钟级），但客户端如果猛打流量，扩容来不及就会熔断。
  • 排查思路：按策略控制爬坡：使用排队 Header（首选）、QPS 爬坡器、削峰填谷或跨模型分流。核心动作对比见 标准流程 · 阶段二：突发流量爬坡。
  • 深度阅读：

客户端超时不够导致断连#

  • 现象：调用深度思考模型时频繁超时报错；非流式模式下长时间无响应后断开连接，任务未完成且已产生 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 也要相应调大。
  • 深度阅读：

同模型多 Endpoint / 多账号分流无效#

  • 现象：客户为了规避限流，创建多个 Endpoint 或用多个账号轮询调用同一个模型，结果仍然 429。
  • 原因：方舟模型限流是同主账号下同模型共享的，不区分版本。可以对自定义推理接入点单独限流，但同一模型的所有 Endpoint 和账号底层共享同一个资源池，流量最终汇聚。
  • 排查思路：
    • 改用跨模型分流：如同时调用 seed-2.1-pro 和 seed-2.0-pro，不同模型资源池独立。
    • 提工单扩容配额：单模型账号级配额提升。
    • 配合排队 Header 与 QPS 爬坡：控制发送速率。
  • 深度阅读：

冷启动首请求报错#

  • 现象：长时间没有流量的 Endpoint，突然调用时报 ServerOverloaded / InflightBatchsizeExceeded，但过一会儿再调就正常了。
  • 原因：
    • ServerOverloaded：长时间无流量时服务缩容，第一个请求撞上扩容过程。
    • InflightBatchsizeExceeded：服务过载熔断，限制该时段内有突发请求、新上量的客户；流量平稳的客户不受影响。
  • 排查思路：
    • 携带排队 Header：请求加 X-Ark-Max-Wait-Timeout-Ms，给服务端扩容留出时间。
    • 客户端爬坡预热：从低 QPS 开始逐步提升，不要一上来就打满。
    • 错峰触发定时任务：避免集中冷启动。
    • 申请提额（仅限 InflightBatchsizeExceeded）：非默认 TPM 能够豁免系统熔断。
  • 深度阅读：

代理导致连接失败#

  • 现象：调用方舟 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}。
  • 深度阅读：
    • 流式输出：流式响应的完整拼接逻辑与最佳实践。

接入配置问题#

model 字段建议使用 Endpoint ID 而非 Model ID#

  • 现象：生产环境使用 Model ID 调用，难以做限流配置、版本切换和监控。
  • 原因：Endpoint ID（形如 ep-********）可以对模型调用做更精细化的管理。
  • 排查思路：
    • 快速验证用 Model ID：新用户可以直接用 Model ID 或预置接入点 Endpoint ID。
    • 生产环境用 Endpoint ID：创建自定义推理接入点，用 Endpoint ID 调用，便于做限流配置、版本切换和监控。
  • 深度阅读：

不同协议 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 生态工具。
  • 深度阅读：

选型注意事项#

Responses API 不支持保障包 / 精调模型 / 智能路由#

  • 现象：新业务按推荐上了 Responses API，后续要接 TPM 保障包或精调模型时发现不支持，得回退 Chat API，返工成本高。
  • 原因：Responses API 目前不支持以下功能：TPM 保障包（已几乎不再售卖）、精调后模型的在线推理、智能模型路由、在线推理服务的模型版本平滑切换。
  • 排查思路：
    • 新业务优先 Responses API：如果明确不需要 TPM 保障包 / 精调 / 智能路由，选它（自动上下文管理、内置工具、缓存降本）。
    • 有历史依赖继续 Chat API：如果已有或计划使用精调模型、保障包，继续用 Chat API。
  • 深度阅读：