# 模型接入指南（LLM） - 性能评测

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

本指南面向**已完成接入、准备上线放量前需要跑一次性能基线评测**的场景（也称压测 / benchmark / 性能测试），在自有环境下对方舟模型推理接入点做一次标准化压测，产出可信、可复现的性能报告。

- **测什么**：TTFT（首 token 延迟）、TPOT（每 token 间隔）、E2E（端到端耗时）、缓存命中率。
- **怎么测**：优先在同机同网环境，用自有压测工具或方舟提供的 llm-bench 工具，跑「前缀复用」及「多轮长上下文」两类场景。
- **交付什么**：把生成的 `reports/prefix_<时间戳>/` 和 `reports/multiturn_<时间戳>/` 目录打包，发给您的客户经理或后算服务工程师。

## 核心指标口径

大语言模型采用流式逐 token 生成方式，用户实际体验由以下四项核心指标决定：

| 指标 | 定义 | 计算口径 | 主要影响因素 |
| --- | --- | --- | --- |
| **TTFT**（Time to First Token，首字延迟） | 从请求发出到收到首个输出 token 的时间 | `TTFT = 首个 token 到达时间 − 请求发送时间`（含网络往返） | 与输入长度强相关（评测时需统一约定输入长度）；与缓存命中率强相关 |
| **E2E 延迟**（端到端总耗时） | 从请求发出到收到最后一个输出 token 的总耗时 | `E2E = 最后内容 chunk 到达时间 − 请求发送时间` | 与输入 / 输出长度均强相关 |
| **TPOT**（Time Per Output Token） | 输出阶段 token 生成速率，即相邻两个输出 token 之间的平均间隔 | `TPOT = (E2E − TTFT) / (输出 token 数 − 1)` | 长输出下趋于稳定 |
| **缓存命中率** | 请求输入中命中缓存的 token 数占总输入 token 数的比例 | `cached_tokens / prompt_tokens × 100%`（按 token 加权平均） | 直接影响 TTFT；命中率越高，推理成本越低 |

在 Agent、Coding 等对响应实时性敏感的场景中，这 4 项指标是评估模型能否满足业务需求的核心依据。

统计分位建议同时记录 AVG（平均值，反映整体水平）、P50（中位数，典型用户体验）、P99（99 分位，反映长尾抖动）。

## 测试准备

请在您自己的环境下，结合线上平均输入长度在「固定前缀 + 变化后缀」场景对方舟模型接入点跑一次评测。**同机同网、参数对齐**是有效结论的前提。

评测前请确认以下参数已经对齐：

- **模型版本**：方舟 Endpoint / Model ID 明确记录。
- **reasoning_effort**：本次评测的取值保持一致（如统一 `none` 或 `high`）。
- **max_completion_tokens / max_output_tokens**：一致。
- **输入 / 输出长度**：前缀长度、后缀长度、多轮上下文长度对齐。
- **并发数**：`max_concurrency` 一致。
- **思考口径**：`reasoning_effort` 保持一致，避免"这次思考、下次不思考"造成的错位对比。

## 测试工具选择

| 您的情况 | 选用工具 |
| --- | --- |
| 已有 vLLM `benchmark_serve` / SGLang `bench_serving` 等压测工具 | 沿用自有工具，按线上输入 / 输出长度参数配置即可 |
| 没有现成工具 | 用方舟提供的 llm-bench 工具（OpenAI Chat 协议，指标口径对齐 vLLM `benchmark_serve`） |

llm-bench 有两种使用方式，任选其一：

- **一键 Agent Skill**（推荐）：使用 Claude Code、豆包企业版等 Agent 工具的用户可一键安装，自然语言即可触发压测。详见 [一键 Skill 压测](/docs/go-live-benchmark-guide#one-click-skill)。
- **命令行直接跑**：熟悉 shell 的用户可从 Skill 包获取 llm-bench 源码后手动运行。详见 [命令行压测步骤](/docs/go-live-benchmark-guide#cli-steps)。

<span id="one-click-skill"></span>

## 一键 Skill 压测

### 前置条件

- **Node.js ≥ 18** 与 npm（用于运行 `npx skills` 命令）。
- **Ark CLI** 已安装并完成 SSO 登录：

  ```bash
  npm install -g @volcengine/ark-cli@latest
  arkcli auth login volc-sso
  ```

  Skill 内部通过 Ark CLI 获取 API Key 与推理接入点信息，若未安装则触发 skill 会报 `arkcli is required`。

- **支持 Agent Skill 的工具**：Claude Code、豆包企业版、Codex、Trae 等。`npx skills add` 命令会自动写入这些工具的 skill 目录，重新打开会话即可加载。

### 安装 skill

```bash
npx --yes skills@latest add "https://arkdocs.tos-cn-beijing.volces.com/skills/" \
  --skill ark-model-benchmark \
  --yes
```

### 触发压测

安装完成后，用自然语言触发即可，例如："帮我压测一下方舟上豆包 Seed 2.0 Mini 模型的性能"。Skill 会自动完成 Ark CLI 登录检查、模型解析、连通性 / Prefix / Multi-turn 三种场景压测，并在 `reports/` 目录下输出 Markdown 报告与 PNG 图表。

<span id="cli-steps"></span>

## 命令行压测步骤

### Step 1 · 获取 llm-bench

Skill 包内嵌了 llm-bench 源码（含 `run_prefix.sh` / `run_multiturn.sh` / 语料 / 报告模板等）。先按 [一键 Skill 压测 · 安装 skill](/docs/go-live-benchmark-guide#one-click-skill) 安装 skill，然后从 skill 目录取出 `llm_bench/`：

```bash
# skills CLI 通常会用 symlink 部署，find 必须加 -L 才能跟随
LLM_BENCH_DIR=$(find -L ~/.claude/skills .claude/skills .agents/skills \
  -maxdepth 5 -type d -name llm_bench 2>/dev/null | head -1)
echo "$LLM_BENCH_DIR"    # 应输出类似 .claude/skills/ark-model-benchmark/llm_bench
cp -r "$LLM_BENCH_DIR" ./llm_bench
cd llm_bench
```

若您不使用 Skill CLI，也可以联系客户经理或后算服务工程师直接获取 llm-bench zip 包。

### Step 2 · 安装依赖

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

export ARK_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
export ARK_API_KEY="<YOUR_ARK_API_KEY>"
```

### Step 3 · 连通性自检

将 `<ep-********>` 替换为方舟推理接入点 ID 或 Model ID：

```bash
# 发 1 个请求验证地址 / 密钥 / 模型可用，并打印 TTFT / usage / cached_tokens
python bench.py connectivity --model <ep-********>
```

### Step 4 · 正式压测

llm-bench 提供两个入口脚本，分别对应「前缀复用」与「多轮长上下文」两个核心场景：

```bash
# 直接跑
./run_prefix.sh
./run_multiturn.sh

# 覆盖参数：环境变量前置即可
MAX_CONCURRENCY=20 PREFIX_LEN=12000 SUFFIX_LEN=2000 NUM_REQUESTS=200 \
./run_prefix.sh

# multiturn：想让命中率曲线更平滑可提到 50 个 session
MAX_CONCURRENCY=10 NUM_SESSIONS=50 MAX_TURNS=20 \
./run_multiturn.sh
```

> **注意**
>
> 请在同机同网条件下测试。网络往返或代理会让 TTFT / E2E 明显虚高，导致结论失真。

### Step 5 · 交付报告

跑完自动生成目录 `reports/prefix_<时间戳>/` 和 `reports/multiturn_<时间戳>/`（多次运行互不混杂）。请把这两个目录打包，发给您的客户经理或后算服务工程师。

拿到同口径数据后，若方舟指标与您的预期确有差距，我们会分析差距并进一步优化；若差距源于口径或环境差异，也能第一时间澄清。

## 报告示例

llm-bench 生成的报告示例（片段）如下，可作为汇报格式参考。

### 前缀复用（Prefix）场景

````markdown
# LLM Benchmark Report - prefix

- **压测时间**: 2026-08-28 13:37:57
- **模式**: prefix
- **API 地址**: https://ark.cn-beijing.volces.com/api/v3
- **长度口径**: tiktoken（精确切片）
- **max_completion_tokens**: 512
- **reasoning_effort**: none
- **prefix_len**: 12000
- **suffix_len**: 2000
- **num_requests**: 200
- **max_concurrency**: 5

## 结果总览

| 模型 | 成功/失败 | TTFT avg (ms) | TTFT P99 (ms) | TPOT avg (ms) | E2E avg (ms) | 加权缓存命中率 |
|---|---|---|---|---|---|---|
| deepseek-v4-flash-ga-260731 | 200/0 | 2278.7 | 3362.4 | 10.4 | 6421.3 | 77.85% |
````

### 多轮长上下文（Multi-turn）场景

````markdown
# LLM Benchmark Report - multiturn

- **压测时间**: 2026-08-28 13:42:35
- **模式**: multiturn
- **max_completion_tokens**: 1024
- **initial_len**: 3000
- **question_len**: 256
- **num_conversations**: 10
- **max_turns**: 20
- **max_concurrency**: 5
- **长度形态**: Turn1 输入 3000 tokens，追问各 256 tokens，回答各 ≤1024 tokens，最终轮 ≈ 27320 tokens
- **429 / 网络重试次数**: 0

## 结果总览

| 模型 | 成功/失败 | TTFT avg (ms) | TTFT P99 (ms) | TPOT avg (ms) | E2E avg (ms) | 加权缓存命中率 |
|---|---|---|---|---|---|---|
| deepseek-v4-flash-ga-260731 | 200/0 | 2260.9 | 3435.6 | 10.1 | 11824.6 | 87.87% |
````

## 常见无效反馈示例

以下反馈因缺少量化指标或口径信息，无法定位问题，也无法澄清是否为口径差异。请按上一节报告格式提供数据：

| 无效反馈 | 为什么无效 |
| --- | --- |
| 跑起来感觉很慢 | 纯主观，无量化指标，分不清慢在首 token 还是整体输出 |
| 首 token 出现的很慢，但不说输入长度 | TTFT 与输入长度、缓存命中率强相关，无法判断是否正常 |
| 提供了对比结论，但两边参数设定不明确 | 口径不对齐的对比没意义，差距可能来自思考等级参数差异，导致 E2E 拉长 |
| 只发一句「性能不达标」 | 无原始报告和数据，无法定位也无法澄清是否口径差异 |

## 附录：方舟推理服务性能观测

为便于实时观测性能指标，方舟控制台提供了性能观测入口，可以按不同输入长度查看不同测试指标：<https://ark.volcengine.com/region:cn-beijing/model/leaderboard>。

## 附录：结果偏差解读

拿到评测结果后，如遇到指标异常，可对照下表定位：

- **`cached_tokens` 异常偏低**：多轮请求缓存未命中，参见 [常见问题 · 缓存失效](/docs/go-live-faq#cache-invalidation)。
- **TTFT 异常偏高**：可能是深度思考模型输出偏长，或客户端超时不够，参见 [常见问题 · 客户端超时不够导致断连](/docs/go-live-faq#client-timeout)。
- **fast 模式延迟不稳定**：低延迟模式发生降级，参见 [常见问题 · 低延迟模式非 100% 生效](/docs/go-live-faq#low-latency-degradation)。