火山方舟
火山方舟
资源
请输入
- 文档首页
火山方舟上线到生产模型接入指南（LLM） - 标准流程
复制全文
下载 pdf模型接入指南（LLM） - 标准流程
文档反馈
问问助手本文面向已调通 API、准备将方舟大模型接入生产环境的开发者，介绍从联调到上线放量的完整接入步骤（也称上线流程、放量流程、onboarding）。全文按三个阶段推进：小流量测试（参数配置、Harness 接入、联通性核验、性能基线评测） → 突发流量爬坡（排队 Header、QPS 爬坡、削峰填谷、跨模型分流） → 生产上量（429 错误码分类、缓存命中率、截断检测、低延迟降级监控）。
说明
接入前请先了解
接入方舟大模型服务前，建议按下方三阶段顺序推进：先在小流量上验证参数与联通性，再按预估流量做爬坡演练，最后放开生产流量。
- 阶段一 · 小流量测试：完成参数配置、Harness 接入、联通性核验、性能基线评测。
- 阶段二 · 突发流量爬坡：控制 Token 用量增长斜率在每 3 分钟 ≤ 20%。
- 阶段三 · 生产环境正式大流量上量：持续监控 429 分类、缓存命中率、截断与低延迟降级。
接入流程总览
按下表顺序推进，每个阶段完成后再进入下一阶段：
阶段一：小流量测试
验证参数与联通性、跑出性能基线报告。
1. 完成推荐参数配置
Agent / Coding 场景下，max_tokens、thinking、reasoning_effort、采样参数、思考内容回传方式、缓存排布与客户端超时都会显著影响效果与稳定性。首次调用前请按以下推荐值配置：
配置项 | 推荐值 | 配置错误的后果 |
max_tokens / max_completion_tokens | 显式传入 ≥ 128000 | 回答被截断、工具参数 JSON 不完整、Agent Loop 中断 |
thinking | {"type": "enabled"} | 多步任务规划能力下降 |
reasoning_effort | high 或以上 | 低档位思考不足，工具选择与参数构造错误率上升 |
temperature | 1 | 影响工具调用稳定性和推理质量 |
top_p | 0.95 | 不建议同时大幅调整两项采样参数 |
思考内容回传 | 按模型类别选明文 / 加密回传 | |
客户端超时 | 非流式 ≥ 30 分钟；流式 SDK 超时 > 排队时间 | 深度思考输出长、生成慢，默认超时可能会断连 |
字段完整清单与取值原因：
- Agent 场景模型调用的正确姿势：完整参数矩阵与常见问题定位。
- 上下文缓存：缓存生效条件与命中原则。
2. 接入三方 Harness
Claude Code、Codex 等三方 Harness 需要配置 Base URL、模型位、Token、超时、思考等级等一系列环境变量。
前置准备：
- 获取 ARK_API_KEY：登录方舟控制台 API Key 管理 创建 API Key。
Model ID 与 Endpoint ID 的选择：小流量测试可直接使用 Model ID；生产环境建议全部替换为 Endpoint ID（形如 ep-********），以便按接入点做限流、监控与版本切换。详见 常见问题 · model 字段建议使用 Endpoint ID。
2.1 Claude Code
将以下内容写入 ~/.claude/settings.json 或项目 .claude/settings.json 的 env 字段：
注意
Haiku / Sonnet / Opus 三个模型位都要配。Claude Code 内部会根据任务复杂度自动切换模型位，只配 ANTHROPIC_MODEL 不够，子任务可能 fallback 到默认模型导致效果不可控。
- ANTHROPIC_DEFAULT_HAIKU_MODEL：建议配 lite / mini 类小尺寸模型（例如 doubao-seed-2-0-lite-260428），可以显著降低端到端延时。
- CLAUDE_CODE_SUBAGENT_MODEL：建议与主模型 ANTHROPIC_MODEL 保持一致。
2.2 Codex
将以下内容写入 ~/.codex/config.toml：
在 shell 中导出 API Key：
注意
- 部分模型不支持 reasoning summaries：minimax-m2.7、kimi-k2.6、kimi-k2.7-code 接入时需要移除 model_supports_reasoning_summaries = true 配置项。
- 请求 Header 必须携带 User-Agent：可取 codex_appserver 或 codex，否则会报错 json: unknown field "client_metadata"。若客户端无法修改，可将其 User-Agent 加入白名单。
参考请求示例：
其余 Harness 的完整字段与接入方式：
- Claude Code：Claude Code 的接入示例。
3. 联通测试
首次调用前依次核验以下项，任一失败都会导致上量后翻车：
- 测试 API 连通性：ping ark.cn-beijing.volces.com 应可解析且延迟正常。
- 确认 Base URL 与协议匹配：OpenAI 兼容 /api/v3；Anthropic 兼容 /api/compatible。协议选型详见 常见问题 · 不同协议 Base URL 不同。
- 确认 model 字段格式：生产环境用 Endpoint ID，快速验证可用 Model ID。
- 确认代理配置（如有）：未阻断到方舟域名的连接，处理办法见 常见问题 · 代理导致连接失败。
- 发送少量测试请求：验证思考内容正常返回、finish_reason 非 length、cached_tokens 字段有值。
4. 性能基线评测
阶段二：突发流量爬坡
控制流量增长斜率，规避 429 / RequestBurstTooFast 突发保护。
方舟对流量增长斜率有保护机制，Token 用量增长速率建议控制在每 3 分钟 ≤ 20%。此处"流量爬坡"也称放量、上量、灰度切流、突增控速——本节讲的都是同一件事：如何把流量从小到大平滑推上去、避免撞上突发保护。可组合使用的四种策略（按改造成本从低到高）：
策略 | 适用场景 | 核心动作 |
排队 Header（首选） | 所有场景通用，零代码改造 | 请求加 X-Ark-Max-Wait-Timeout-Ms: 300000，服务端排队而非直接报错。客户端超时需要同步调大。 |
QPS 爬坡器 | 可控的持续流量增长 | 从 5–50 QPS 起步，按错误率动态调整；配合指数退避重试。 |
削峰填谷 | 不可预测的瞬时峰值（如热点事件） | 用 MQ 无限制接收（削峰），消费端匀速消费（填谷），斜率恒定。 |
跨模型分流 | 高稳定性核心业务 | 不同模型资源池独立，可分散压力。同模型多 Endpoint / 多账号分流无效（共享资源池）。 |
1. 排队 Header（首选）
在请求 Header 中加入 X-Ark-Max-Wait-Timeout-Ms（单位毫秒），服务端命中突发限流时会自动排队，而不是直接返回 429。建议值范围为 [60000, 600000]（1–10 分钟）。
注意
客户端超时必须同步调大：非流式超时 = 基础超时 + 排队时间；流式 Python / Java SDK 超时 > 排队时间即可。排队 5 分钟但客户端 30 秒超时断开等于白等。
Python 示例：
2. QPS 爬坡器
客户端从低 QPS 起步（建议 5–50），根据限流错误率动态调整：
- 错误率 ≥ 5%：降速。
- 错误率 1%–5%：维持当前 QPS。
- 错误率 < 1%：小幅探测提升。
- 错误率 0%：积极提升。
配合指数退避重试（初始 100ms，最大 3s，加随机抖动）。参考参数：
3. 削峰填谷
- 用 MQ（如 RabbitMQ 持久化队列 + 手动 ACK）无限制接收请求，削掉客户端瞬时峰值。
- 消费端按恒定斜率匀速消费，例如从 5 QPS 起步、每 5 秒 +2 QPS：
4. 跨模型分流
仅支持跨模型分流（如模型 A + 模型 B），不同模型资源池独立。同模型多 Endpoint / 多账号分流无效——同一模型底层共享资源池。
四种策略的完整参数、代码示例与错误码识别方法：
- 突发流量处理最佳实践：突发流量处理最佳实践。
收到 429 时先看 error.code 区分类型：ModelAccountTpmRateLimitExceeded 是配额限流（需扩容）；ServerOverloaded / RequestBurstTooFast 是突发保护（需控斜率，扩容无效）。详见 常见问题 · 429 分不清配额超限还是突发流量限流。
阶段三：生产环境正式大流量上量
持续监控 429 分类、缓存命中率、截断、低延迟降级。
按已选定的爬坡策略逐步放开生产流量，同时持续关注以下指标：
- 429 错误码分类：区分配额限流与突发保护。错误码含义见 错误码。
- 缓存命中率：观察响应中的 cached_tokens 字段，TTFT 异常飙升时排查参数稳定性与系统提示词 / 工具定义的排列，详见 上下文缓存。
- 截断检测：finish_reason / stop_reason 为 length 即被截断，需调大 max_tokens。
- 低延迟降级比例：如使用 service_tier=fast，关注 fast → default 降级量与降级触发条件，详见 在线推理（低延迟）。
上线前检查清单（Checklist）
按此清单逐项核对，全部勾选后可进入正式生产环境放量。也可拷贝到内部工单 / MR 描述，供跨团队验收使用。
阶段一：小流量测试
max_tokens / max_completion_tokens ≥ 128000 已显式传入。
thinking={"type": "enabled"}，reasoning_effort=high（或更高档位）。
temperature=1、top_p=0.95。
思考内容回传方式已按模型类别选定（明文 / 加密块），并已在业务代码中落地。
客户端超时：非流式 ≥ 30 分钟；流式 SDK 超时 > 服务端排队时间。
已获取 ARK_API_KEY 与 ep-******** 形态的 Endpoint ID。
联通性自检通过：思考内容正常返回、finish_reason 非 length、cached_tokens 字段有值。
阶段二：突发流量爬坡
已确认预估峰值 TPM / RPM 与账号配额上限的差距。
已在客户端加上 X-Ark-Max-Wait-Timeout-Ms 排队 Header，客户端超时同步调大。
有匹配的 QPS 爬坡逻辑（或使用 QPS 爬坡器策略）。
对突发峰值场景（热点事件、定时任务）有削峰填谷或跨模型分流兜底。
已理解 429 两类错误码的区分方法（配额限流 vs 突发保护）。
阶段三：生产上量
429 错误码分类监控与告警已配置（ModelAccountRpmRateLimitExceeded / ModelAccountTpmRateLimitExceeded / ServerOverloaded / RequestBurstTooFast 分别告警）。
缓存命中率（cached_tokens）监控已配置，异常降低触发告警。
截断检测（finish_reason / stop_reason == length）监控已配置。
如使用 service_tier=fast，fast → default 降级比例监控已配置。
最近更新时间：2026.11.03 15:22:53
这个页面对您有帮助吗？
有用
有用
无用
无用