模型接入指南（LLM） - 标准流程

本文面向已调通 API、准备将方舟大模型接入生产环境的开发者，介绍从联调到上线放量的完整接入步骤（也称上线流程、放量流程、onboarding）。全文按三个阶段推进：小流量测试（参数配置、Harness 接入、联通性核验、性能基线评测） → 突发流量爬坡（排队 Header、QPS 爬坡、削峰填谷、跨模型分流） → 生产上量（429 错误码分类、缓存命中率、截断检测、低延迟降级监控）。

接入流程总览#

按下表顺序推进，每个阶段完成后再进入下一阶段：

阶段一：小流量测试#

验证参数与联通性、跑出性能基线报告。

1. 完成推荐参数配置#

Agent / Coding 场景下，max_tokens、thinking、reasoning_effort、采样参数、思考内容回传方式、缓存排布与客户端超时都会显著影响效果与稳定性。首次调用前请按以下推荐值配置：

字段完整清单与取值原因：

• Agent 场景模型调用的正确姿势：完整参数矩阵与常见问题定位。
• 上下文缓存：缓存生效条件与命中原则。

2. 接入三方 Harness#

Claude Code、Codex 等三方 Harness 需要配置 Base URL、模型位、Token、超时、思考等级等一系列环境变量。

前置准备：

• 获取 ARK_API_KEY：登录方舟控制台 API Key 管理 创建 API Key。
• 获取 Endpoint ID：登录方舟控制台 推理接入点 创建自定义推理接入点，拿到 ep-******** 形态的 ID。创建流程详见 创建推理接入点。

Model ID 与 Endpoint ID 的选择：小流量测试可直接使用 Model ID；生产环境建议全部替换为 Endpoint ID（形如 ep-********），以便按接入点做限流、监控与版本切换。详见 常见问题 · model 字段建议使用 Endpoint ID。

2.1 Claude Code#

将以下内容写入 ~/.claude/settings.json 或项目 .claude/settings.json 的 env 字段：

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "<YOUR_ARK_API_KEY>",
    "ANTHROPIC_BASE_URL": "https://ark.cn-beijing.volces.com/api/compatible",
    "ANTHROPIC_MODEL": "<YOUR_ENDPOINT_ID>",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "<YOUR_ENDPOINT_ID>",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "<YOUR_ENDPOINT_ID>",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "<YOUR_ENDPOINT_ID>",
    "CLAUDE_CODE_SUBAGENT_MODEL": "<YOUR_ENDPOINT_ID>",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "128000",
    "API_TIMEOUT_MS": "1800000"
  }
}

2.2 Codex#

将以下内容写入 ~/.codex/config.toml：

1
2
3
4
5
6
7
8
9
10
11
12
13model = "<YOUR_ENDPOINT_ID>"
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：

1export ARK_API_KEY="<YOUR_ARK_API_KEY>"

参考请求示例：

1
2
3
4
5
6
7
8
9
10
11curl '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": "<YOUR_ENDPOINT_ID>",
    "input": "只回复 OK",
    "stream": false,
    "max_output_tokens": 128,
    "store": false
  }'

其余 Harness 的完整字段与接入方式：

• 接入三方工具：Chatbox、Cherry Studio、OpenCode、TRAE、Cursor、Cline 等工具的接入示例。

配置完成后若出现模型不思考、子任务用错模型等异常，请参见 常见问题 · Harness 关键配置缺失 逐项排查。

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. 性能基线评测#

完成参数与联通性验证后，按标准化脚本跑一次性能基线评测，避免用主观感受判断"快 / 慢"。详见 模型接入指南（LLM） - 性能评测。

阶段二：突发流量爬坡#

控制流量增长斜率，规避 429 / RequestBurstTooFast 突发保护。

方舟对流量增长斜率有保护机制，Token 用量增长速率建议控制在每 3 分钟 ≤ 20%。此处"流量爬坡"也称放量、上量、灰度切流、突增控速——本节讲的都是同一件事：如何把流量从小到大平滑推上去、避免撞上突发保护。可组合使用的四种策略（按改造成本从低到高）：

1. 排队 Header（首选）#

在请求 Header 中加入 X-Ark-Max-Wait-Timeout-Ms（单位毫秒），服务端命中突发限流时会自动排队，而不是直接返回 429。建议值范围为 [60000, 600000]（1–10 分钟）。

Python 示例：

1
2
3
4
5
6
7
8
9completion = client.chat.completions.create(
    model="<YOUR_ENDPOINT_ID>",
    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，加随机抖动）。参考参数：

1Options{InitialRate:10, MaxRate:1000, AdjustInterval:10s, StrictErrorRatio:0.05}

3. 削峰填谷#

• 用 MQ（如 RabbitMQ 持久化队列 + 手动 ACK）无限制接收请求，削掉客户端瞬时峰值。
• 消费端按恒定斜率匀速消费，例如从 5 QPS 起步、每 5 秒 +2 QPS：

1FLOW = {"curr_qps": 5, "max_qps": 30, "step": 2, "interval": 5, "count": 0}

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 降级量与降级触发条件，详见 在线推理（低延迟）。

若遇到效果、可用性或选型问题，请对照 模型接入指南（LLM） - 常见问题 逐项排查。指标稳定后即进入常态运维。

上线前检查清单（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 落地。
• 联通性自检通过：思考内容正常返回、finish_reason 非 length、cached_tokens 字段有值。
• 性能基线评测已跑完（模型接入指南（LLM） - 性能评测），产出 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） - 常见问题，理解常见问题的现象、原因与排查路径。