火山方舟
火山方舟
资源
请输入
- 文档首页
火山方舟上线到生产模型接入指南（LLM） - 常见问题
复制全文
下载 pdf模型接入指南（LLM） - 常见问题
文档反馈
问问助手本文汇总方舟大模型接入 / 上线过程中的常见问题（效果、可用性、接入配置、选型四类），每个问题按 现象 → 原因 → 排查思路 → 深度阅读 组织。同类问题也可能被称作"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 场景模型调用的正确姿势：各 API 字段矩阵、明文 / 加密支持模型清单、完整代码示例与流式响应处理规则。
Harness 关键配置缺失
- 现象：用 Codex CLI、Claude Code 等工具接入后，模型不思考、不走 Responses API、子任务用错模型，可能导致效果差很多。
- 原因：三方 Harness 涉及多个模型位、超时、思考等级等环境变量，任一缺失都会导致行为退化。
注意
Agent / Coding 场景不推荐使用 Chat API。Codex 优先使用 Responses API，Claude Code 使用 Anthropic 兼容 API。
- 排查思路：对照完整配置示例逐项核查。完整配置模板已放在 标准流程 · 接入三方 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：Claude Code / Codex 完整 JSON / TOML 配置示例与说明。
- Claude Code：Claude Code 的接入示例。
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 场景模型调用的正确姿势：输出长度参数配置章节。
缓存失效
- 现象：多轮对话越聊越慢（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 也要相应调大。
- 深度阅读：
- 深度思考：深度思考模型的输出时长与包间延迟说明。
- 突发流量处理最佳实践：排队 Header 与客户端超时的配套关系。
- 现象：客户为了规避限流，创建多个 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）。
- 排查思路：禁用代理或加白名单：
-
- 或设置环境变量 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 生态工具。
- 深度阅读：
- Claude Code：Claude Code 的完整 Base URL 与 Header 配置。
选型注意事项
Responses API 不支持保障包 / 精调模型 / 智能路由
- 现象：新业务按推荐上了 Responses API，后续要接 TPM 保障包或精调模型时发现不支持，得回退 Chat API，返工成本高。
- 原因：Responses API 目前不支持以下功能：TPM 保障包（已几乎不再售卖）、精调后模型的在线推理、智能模型路由、在线推理服务的模型版本平滑切换。
- 排查思路：
- 新业务优先 Responses API：如果明确不需要 TPM 保障包 / 精调 / 智能路由，选它（自动上下文管理、内置工具、缓存降本）。
- 有历史依赖继续 Chat API：如果已有或计划使用精调模型、保障包，继续用 Chat API。
- 深度阅读：
- 迁移至 Responses API：Responses API 与 Chat API 的功能矩阵与迁移指南。
最近更新时间：2026.11.03 15:22:53
这个页面对您有帮助吗？
有用
有用
无用
无用