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

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

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

> **说明**
>
> **如果你还没调通第一个请求**，请先阅读 [快速入门](/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"}` | 用 `auto` 时模型可能跳过推理，多步任务规划能力下降 |
| `reasoning_effort` | `high` 或以上 | 低档位思考不足，工具选择与参数构造错误率上升 |
| `temperature` | `1` | 影响工具调用稳定性和推理质量 |
| `top_p` | `0.95` | 不建议同时大幅调整两项采样参数 |
| 思考内容回传 | 按模型类别选明文 / 加密回传 | 推理连续性打断、缓存失效、成本上升，详见 [常见问题 · 思考内容回传](/docs/go-live-faq#thinking-content-return) |
| 客户端超时 | 非流式 ≥ 30 分钟；流式 SDK 超时 > 排队时间 | 深度思考输出长、生成慢，默认超时可能会断连 |

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

- [Agent 场景模型调用的正确姿势](/docs/agent-model-invocation-practice)：完整参数矩阵与常见问题定位。
- [上下文缓存](/docs/context-cache)：缓存生效条件与命中原则。

<span id="third-party-harness"></span>

### 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。创建流程详见 [创建推理接入点](/docs/create-endpoint-api)。

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

### 2.1 Claude Code

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

```json
{
  "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"
  }
}
```

> **注意**
>
> **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 = "<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：

```bash
export ARK_API_KEY="<YOUR_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": "<YOUR_ENDPOINT_ID>",
    "input": "只回复 OK",
    "stream": false,
    "max_output_tokens": 128,
    "store": false
  }'
```

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

- [接入三方工具](/docs/integrate-third-party-tools)：Chatbox、Cherry Studio、OpenCode、TRAE、Cursor、Cline 等工具的接入示例。

配置完成后若出现模型不思考、子任务用错模型等异常，请参见 [常见问题 · Harness 关键配置缺失](/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 不同](/docs/go-live-faq#base-url)。
- **确认 model 字段格式**：生产环境用 Endpoint ID，快速验证可用 Model ID。
- **确认代理配置**（如有）：未阻断到方舟域名的连接，处理办法见 [常见问题 · 代理导致连接失败](/docs/go-live-faq#proxy-connection-failure)。
- **发送少量测试请求**：验证思考内容正常返回、`finish_reason` 非 `length`、`cached_tokens` 字段有值。

### 4. 性能基线评测

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

<span id="traffic-burst-strategy"></span>

## 阶段二：突发流量爬坡

> **控制流量增长斜率，规避 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="<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，加随机抖动）。参考参数：

```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 / 多账号分流无效**——同一模型底层共享资源池。

四种策略的完整参数、代码示例与错误码识别方法：

- [突发流量处理最佳实践](/docs/traffic-burst-handling-best-practices)：突发流量处理最佳实践。

收到 429 时先看 `error.code` 区分类型：`ModelAccountTpmRateLimitExceeded` 是配额限流（需扩容）；`ServerOverloaded` / `RequestBurstTooFast` 是突发保护（需控斜率，扩容无效）。详见 [常见问题 · 429 分不清配额超限还是突发流量限流](/docs/go-live-faq#classify-429)。

## 阶段三：生产环境正式大流量上量

> **持续监控 429 分类、缓存命中率、截断、低延迟降级。**

按已选定的爬坡策略逐步放开生产流量，同时持续关注以下指标：

- **429 错误码分类**：区分配额限流与突发保护。错误码含义见 [错误码](/docs/error-codes)。
- **缓存命中率**：观察响应中的 `cached_tokens` 字段，TTFT 异常飙升时排查参数稳定性与系统提示词 / 工具定义的排列，详见 [上下文缓存](/docs/context-cache)。
- **截断检测**：`finish_reason` / `stop_reason` 为 `length` 即被截断，需调大 `max_tokens`。
- **低延迟降级比例**：如使用 `service_tier=fast`，关注 fast → default 降级量与降级触发条件，详见 [在线推理（低延迟）](/docs/online-inference-low-latency)。

若遇到效果、可用性或选型问题，请对照 [模型接入指南（LLM） - 常见问题](/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](/docs/go-live-access-sop#third-party-harness) 落地。
- [ ] 联通性自检通过：思考内容正常返回、`finish_reason` 非 `length`、`cached_tokens` 字段有值。
- [ ] 性能基线评测已跑完（[模型接入指南（LLM） - 性能评测](/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） - 常见问题](/docs/go-live-faq)，理解常见问题的现象、原因与排查路径。