本文面向**已调通 API、准备将方舟大模型接入生产环境**的开发者，介绍从联调到上线放量的完整接入步骤（也称上线流程、放量流程、onboarding）。全文按三个阶段推进：**小流量测试**（参数配置、Harness 接入、联通性核验、性能基线评测） → **突发流量爬坡**（排队 Header、QPS 爬坡、削峰填谷、跨模型分流） → **生产上量**（429 错误码分类、缓存命中率、截断检测、低延迟降级监控）。 > **说明** > **如果你还没调通第一个请求**，请先阅读 [快速入门](https://ark.volcengine.com/region:cn-beijing/docs/quick-start)。本文默认你已完成 API Key 获取、单请求调通，从"接入生产"开始讲起。 > **接入前请先了解** > 接入方舟大模型服务前，建议按下方三阶段顺序推进：先在小流量上验证参数与联通性，再按预估流量做爬坡演练，最后放开生产流量。 * > **阶段一 · 小流量测试**：完成参数配置、Harness 接入、联通性核验、性能基线评测。 * > **阶段二 · 突发流量爬坡**：控制 Token 用量增长斜率在每 3 分钟 ≤ 20%。 * > **阶段三 · 生产环境正式大流量上量**：持续监控 429 分类、缓存命中率、截断与低延迟降级。 ## 接入流程总览按下表顺序推进，每个阶段完成后再进入下一阶段： |阶段 |目标 |关键动作 |完成标志 | |---|---|---|---| |**小流量测试** |确认单请求路径打通、参数配置无误 |参数配置 \> 接入 Harness \> 联通测试 \> 性能基线评测 |少量请求稳定成功，性能达到预期 | |**突发流量爬坡** |找到匹配业务的流量爬坡策略 |4 选 1 或组合：排队 Header（首选）/ QPS 爬坡器 / 削峰填谷 / 跨模型分流 |目标峰值下无 `RequestBurstTooFast` 429 | |**生产大流量上量** |稳定运行并做持续观测 |逐步放开生产流量 + 监控 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` |不建议同时大幅调整两项采样参数 | |思考内容回传 |按模型类别选明文 / 加密回传 |推理连续性打断、缓存失效、成本上升，详见 [常见问题 · 思考内容回传](https://ark.volcengine.com/region:cn-beijing/docs/go-live-faq#thinking-content-return) | |客户端超时 |非流式 ≥ 30 分钟；流式 SDK 超时 \> 排队时间 |深度思考输出长、生成慢，默认超时可能会断连 | 字段完整清单与取值原因： * [Agent 场景模型调用的正确姿势](https://ark.volcengine.com/region:cn-beijing/docs/agent-model-invocation-practice)：完整参数矩阵与常见问题定位。 * [上下文缓存](https://ark.volcengine.com/region:cn-beijing/docs/context-cache)：缓存生效条件与命中原则。 ### 2. 接入三方 Harness Claude Code、Codex 等三方 Harness 需要配置 Base URL、模型位、Token、超时、思考等级等一系列环境变量。 **前置准备**： * **获取 ARK_API_KEY**：登录方舟控制台 [API Key 管理](https://ark.volcengine.com/region:cn-beijing/apiKey) 创建 API Key。 * **获取 Endpoint ID**：登录方舟控制台 [推理接入点](https://ark.volcengine.com/region:cn-beijing/endpoint) 创建自定义推理接入点，拿到 `ep-********` 形态的 ID。创建流程详见 [创建推理接入点](https://ark.volcengine.com/region:cn-beijing/docs/create-endpoint-api)。 **Model ID 与 Endpoint ID 的选择**：小流量测试可直接使用 Model ID；生产环境建议全部替换为 Endpoint ID（形如 `ep-********`），以便按接入点做限流、监控与版本切换。详见 [常见问题 · model 字段建议使用 Endpoint ID](https://ark.volcengine.com/region:cn-beijing/docs/go-live-faq#use-endpoint-id)。 ### 2.1 Claude Code 将以下内容写入 `~/.claude/settings.json` 或项目 `.claude/settings.json` 的 `env` 字段： ```json { "env": { "ANTHROPIC_AUTH_TOKEN": "", "ANTHROPIC_BASE_URL": "https://ark.cn-beijing.volces.com/api/compatible", "ANTHROPIC_MODEL": "", "ANTHROPIC_DEFAULT_HAIKU_MODEL": "", "ANTHROPIC_DEFAULT_SONNET_MODEL": "", "ANTHROPIC_DEFAULT_OPUS_MODEL": "", "CLAUDE_CODE_SUBAGENT_MODEL": "", "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "128000", "API_TIMEOUT_MS": "1800000" } } ``` > **注意** > **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`： ```toml model = "" model_provider = "volcengine" model_reasoning_effort = "high" # 若接入 minimax-m2.7 / kimi-k2.6 / kimi-k2.7-code，需删除下一行 model_supports_reasoning_summaries = true model_max_output_tokens = 128000 [model_providers.volcengine] name = "volcengine" base_url = "https://ark.cn-beijing.volces.com/api/v3" wire_api = "responses" env_key = "ARK_API_KEY" stream_idle_timeout_ms = 1800000 ``` 在 shell 中导出 API Key： ```bash export ARK_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` 加入白名单。参考请求示例： ```Bash curl 'https://ark.cn-beijing.volces.com/api/v3/responses' \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -H "User-Agent: codex_appserver" \ -d '{ "model": "", "input": "只回复 OK", "stream": false, "max_output_tokens": 128, "store": false }' ``` 其余 Harness 的完整字段与接入方式： * [接入三方工具](https://ark.volcengine.com/region:cn-beijing/docs/integrate-third-party-tools)：Chatbox、Cherry Studio、OpenCode、TRAE、Cursor、Cline 等工具的接入示例。配置完成后若出现模型不思考、子任务用错模型等异常，请参见 [常见问题 · Harness 关键配置缺失](https://ark.volcengine.com/region:cn-beijing/docs/go-live-faq#harness-config-missing) 逐项排查。 ### 3. 联通测试首次调用前依次核验以下项，任一失败都会导致上量后翻车： * **测试 API 连通性**：`ping ark.cn-beijing.volces.com` 应可解析且延迟正常。 * **确认 Base URL 与协议匹配**：OpenAI 兼容 `/api/v3`；Anthropic 兼容 `/api/compatible`。协议选型详见 [常见问题 · 不同协议 Base URL 不同](https://ark.volcengine.com/region:cn-beijing/docs/go-live-faq#base-url)。 * **确认 model 字段格式**：生产环境用 Endpoint ID，快速验证可用 Model ID。 * **确认代理配置**（如有）：未阻断到方舟域名的连接，处理办法见 [常见问题 · 代理导致连接失败](https://ark.volcengine.com/region:cn-beijing/docs/go-live-faq#proxy-connection-failure)。 * **发送少量测试请求**：验证思考内容正常返回、`finish_reason` 非 `length`、`cached_tokens` 字段有值。 ### 4. 性能基线评测完成参数与联通性验证后，按标准化脚本跑一次性能基线评测，避免用主观感受判断"快 / 慢"。详见 [模型接入指南（LLM） - 性能评测](https://ark.volcengine.com/region:cn-beijing/docs/go-live-benchmark-guide)。 ## 阶段二：突发流量爬坡 > **控制流量增长斜率，规避 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 示例： ```python completion = client.chat.completions.create( model="", messages=[ {"role": "user", "content": "常见的十字花科植物有哪些？"}, ], # 突发流量最大排队时间 300000 毫秒（5 分钟） extra_headers={"X-Ark-Max-Wait-Timeout-Ms": "300000"}, stream=False, ) ``` ### 2. QPS 爬坡器客户端从低 QPS 起步（建议 5–50），根据限流错误率动态调整： * **错误率 ≥ 5%** ：降速。 * **错误率 1%–5%** ：维持当前 QPS。 * **错误率 < 1%** ：小幅探测提升。 * **错误率 0%** ：积极提升。配合指数退避重试（初始 100ms，最大 3s，加随机抖动）。参考参数： ```text Options{InitialRate:10, MaxRate:1000, AdjustInterval:10s, StrictErrorRatio:0.05} ``` ### 3. 削峰填谷 * 用 MQ（如 RabbitMQ 持久化队列 + 手动 ACK）无限制接收请求，削掉客户端瞬时峰值。 * 消费端按恒定斜率匀速消费，例如从 5 QPS 起步、每 5 秒 +2 QPS： ```python FLOW = {"curr_qps": 5, "max_qps": 30, "step": 2, "interval": 5, "count": 0} ``` ### 4. 跨模型分流仅支持**跨模型**分流（如模型 A + 模型 B），不同模型资源池独立。**同模型多 Endpoint / 多账号分流无效**——同一模型底层共享资源池。四种策略的完整参数、代码示例与错误码识别方法： * [突发流量处理最佳实践](https://ark.volcengine.com/region:cn-beijing/docs/traffic-burst-handling-best-practices)：突发流量处理最佳实践。收到 429 时先看 `error.code` 区分类型：`ModelAccountTpmRateLimitExceeded` 是配额限流（需扩容）；`ServerOverloaded` / `RequestBurstTooFast` 是突发保护（需控斜率，扩容无效）。详见 [常见问题 · 429 分不清配额超限还是突发流量限流](https://ark.volcengine.com/region:cn-beijing/docs/go-live-faq#classify-429)。 ## 阶段三：生产环境正式大流量上量 > **持续监控 429 分类、缓存命中率、截断、低延迟降级。** 按已选定的爬坡策略逐步放开生产流量，同时持续关注以下指标： * **429 错误码分类**：区分配额限流与突发保护。错误码含义见 [错误码](https://ark.volcengine.com/region:cn-beijing/docs/error-codes)。 * **缓存命中率**：观察响应中的 `cached_tokens` 字段，TTFT 异常飙升时排查参数稳定性与系统提示词 / 工具定义的排列，详见 [上下文缓存](https://ark.volcengine.com/region:cn-beijing/docs/context-cache)。 * **截断检测**：`finish_reason` / `stop_reason` 为 `length` 即被截断，需调大 `max_tokens`。 * **低延迟降级比例**：如使用 `service_tier=fast`，关注 fast → default 降级量与降级触发条件，详见 [在线推理（低延迟）](https://ark.volcengine.com/region:cn-beijing/docs/online-inference-low-latency)。若遇到效果、可用性或选型问题，请对照 [模型接入指南（LLM） - 常见问题](https://ark.volcengine.com/region:cn-beijing/docs/go-live-faq) 逐项排查。指标稳定后即进入常态运维。 ## 上线前检查清单（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。 - [ ] 三方 Harness（Claude Code / Codex 等）配置文件已按 [接入三方 Harness](https://ark.volcengine.com/region:cn-beijing/docs/go-live-access-sop#third-party-harness) 落地。 - [ ] 联通性自检通过：思考内容正常返回、`finish_reason` 非 `length`、`cached_tokens` 字段有值。 - [ ] 性能基线评测已跑完（[模型接入指南（LLM） - 性能评测](https://ark.volcengine.com/region:cn-beijing/docs/go-live-benchmark-guide)），产出 `reports/prefix_*/` 与 `reports/multiturn_*/` 目录。 **阶段二：突发流量爬坡** - [ ] 已确认预估峰值 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 降级比例监控已配置。 - [ ] 已阅读 [模型接入指南（LLM） - 常见问题](https://ark.volcengine.com/region:cn-beijing/docs/go-live-faq)，理解常见问题的现象、原因与排查路径。

火山方舟