将编码智能体与本地部署的推理服务结合使用

简介

像 opencode、Codex CLI 和 Claude Code 这样的编码智能体,是基于终端的助手,可以读取你的仓库、规划更改、编辑文件,并代你运行命令。它们通常会通过互联网与托管模型提供方通信。

本文档展示了如何将这些智能体指向你在 Alauda AI 上自托管的模型,从而让源代码、prompt 和基础设施配置永远不会离开你的集群。你为任何其他工作负载部署的同一个本地部署 InferenceService 也可以为交互式编码智能体提供支持,只要它暴露 OpenAI-compatible API 并启用了 tool(function)calling。opencode 和 Codex CLI 可以直接调用该端点;Claude Code 使用 Anthropic Messages API(/v1/messages),并且需要一个轻量级翻译代理(参见 Claude Code)。

本页直接基于部署操作指南,不再重复如何创建或暴露 InferenceService;而是链接到相关内容,并聚焦于智能体特定的配置和调优。

WARNING

编码智能体及其配置格式变化很快。下面的配置片段是本文撰写时可用版本的正确起点。请始终对照你所使用智能体的最新上游文档,确认字段名称。

前提条件

  • 一个正在运行且就绪的 InferenceService,提供 OpenAI-compatible API。参见 使用 CLI 创建推理服务。
  • 运行智能体的机器能够访问服务端点的网络。若要从集群外的开发者笔记本访问,参见 为推理服务配置外部访问。
  • 一个支持 tool/function calling 的模型,并使用匹配的 vLLM parser 提供服务(参见 在运行时启用 tool calling)。否则,智能体可以对话,但无法编辑文件或运行命令。
  • 本地已安装智能体 CLI(opencode、codex 或 claude)。
  • 对于 Claude Code,需要一个翻译代理(LiteLLM 或 claude-code-router)将 Claude Code 的 Anthropic Messages API 连接到 OpenAI-compatible 端点(参见 Claude Code)。

各组件如何协同工作

  opencode / Codex CLI
        │  OpenAI Chat Completions API  (POST /v1/chat/completions)
        ▼
  External access / Load Balancer  ──►  KServe InferenceService (vLLM)

  Claude Code
        │  Anthropic Messages API  (POST /v1/messages)
        ▼
  Translation proxy (LiteLLM / claude-code-router)
        │  OpenAI Chat Completions API  (POST /v1/chat/completions)
        ▼
  same InferenceService endpoint
  • opencode 和 Codex CLI 原生支持 OpenAI Chat Completions API,因此可以直接调用 InferenceService 端点。
  • Claude Code 使用 Anthropic Messages API,而 vLLM 不提供该 API。它需要在 OpenAI-compatible 端点前放置一个小型翻译代理(参见 Claude Code)。

第 1 步:部署并对端点进行冒烟测试

按照 使用 CLI 创建推理服务 将模型部署为 InferenceService;如果智能体运行在集群外,则按照 为推理服务配置外部访问 公开该服务。

在接入任何智能体之前,先确认端点能够响应一次聊天请求。如果 base URL、模型名称或认证配置错误,编码智能体会以令人困惑的方式失败,因此请先用 curl 验证:

# BASE_URL must end at /v1
BASE_URL="https://your-inference-service-domain.com/v1"
MODEL="qwen-2"        # must match --served-model-name in the InferenceService
API_KEY="sk-local"    # any non-empty value if the server does not enforce auth

curl -sS ${BASE_URL}/chat/completions \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL}"'",
    "messages": [{"role": "user", "content": "Reply with the single word: ready"}],
    "max_tokens": 16
  }'

正常的 JSON completion 表明端点可达且模型名称正确。请记下后续所有智能体都会复用的三个值:base URL(以 /v1 结尾)、模型名称(--served-model-name)以及 API key。

TIP

对于具备推理能力的模型(在推荐集合中,包括 GLM-5.2 和 Qwen3.6,以及 reasoning-mode Deepseek-v4 构建),还要在 vLLM 启动参数中添加匹配的 --reasoning-parser。参见 配置推理模型和 reasoning effort。

第 2 步:在运行时启用 tool calling

编码智能体通过调用工具(读取文件、写入文件、运行 shell)来工作。这要求模型既要输出 tool call,vLLM 也要能够解析它们。请将以下参数添加到 InferenceService 中的 vLLM 启动命令里(在 使用 CLI 创建推理服务 的示例中,它们位于 python3 -m vllm.entrypoints.openai.api_server 那一行):

--enable-auto-tool-choice \
--tool-call-parser hermes        # match the parser to your model family
  • parser 必须与模型匹配。例如,Qwen2.5 和 QwQ-32B 通常使用 hermes;Qwen3-Coder 使用 qwen3_xml;Llama 3.x 模型使用 llama3_json;Mistral 模型使用 mistral。请查看 vLLM tool calling 文档 获取当前 parser 列表以及与你的模型匹配的值。
  • 某些模型需要特定的 chat template 才能正确输出 tool call;如果模型卡有相关要求,请传入 --chat-template。
  • 如果你提供的是 reasoning model,还要启用匹配的 --reasoning-parser,这样智能体接收到的 assistant content 就会与 reasoning trace 分离,保持干净。

通过让智能体执行一个简单的文件操作来验证端到端 tool calling 是否正常,例如“创建一个包含 hi 这个词的 hello.txt”。如果模型用自然语言回复而不是编辑文件,说明 tool calling 没有正确接通——请重新检查 parser 和模型。

第 2b 步(可选):配置推理模型和 reasoning effort

某些模型会在最终答案之前输出 chain-of-thought 推理。在推荐系列中,这包括 GLM-5.2 和 Qwen3.6(reasoning 默认开启),以及 reasoning-mode Deepseek-v4 构建。vLLM 会将 reasoning trace 与 assistant content 分离,这样智能体接收到的输出会更干净——但你必须启用匹配的参数。

服务端参数

在 vLLM 启动命令中添加 --reasoning-parser。如果同一个模型还需要智能体 tool call,则将其与合适的 --tool-call-parser 配对使用:

--enable-auto-tool-choice \
--tool-call-parser <parser> \
--reasoning-parser <reasoning-parser>

下表列出了 parser 配对以供参考。parser 名称与版本相关,并且会随 vLLM 发布而变化——请始终对照你所运行版本的 vLLM tool calling 文档 进行确认。

模型系列--tool-call-parser--reasoning-parser说明
Qwen3 / Qwen3.6 reasoning (Qwen/Qwen3*)请查看当前 vLLM 文档获取准确的 Qwen 变体qwen3reasoning 默认开启;如有需要,可使用 chat_template_kwargs 将其关闭
GLM-5.2 (Zhipu AI)请查看当前 vLLM 文档获取 GLM 变体请查看当前 vLLM 文档获取 GLM 变体混合推理;tool-call 和 reasoning parser 共享 GLM 家族值
Deepseek-v4 (deepseek_v4)请查看当前 vLLM 文档获取 DeepSeek 变体请查看当前 vLLM 文档获取 DeepSeek 变体仅限 reasoning-mode 构建;参见 DeepSeek-V4-Flash (W4A8) 配方

这些系列的准确 --tool-call-parser / --reasoning-parser 值取决于 vLLM 版本——在定版前请阅读模型卡和 vLLM tool calling 文档,并验证 tool call 能够端到端往返。

配置 reasoning effort 和 thinking 行为

Reasoning effort 决定模型在回答前会“思考”多少。对于编码智能体,通常希望使用 较低 的 reasoning effort,以保持交互延迟可接受——多次简短、低 reasoning 的轮次通常优于一次冗长、高 reasoning 的轮次。

服务端默认值

vLLM 没有暴露通用的 --reasoning-effort 启动参数。全局控制需要通过模型的 chat template 实现:你可以提供一个自定义 Jinja template,默认关闭 thinking,然后通过 --chat-template 传入。或者,某些模型和 vLLM 版本会暴露按模型划分的 template kwargs;请查看对应的 vLLM release notes 获取具体键名。

请求级控制

不要假定每个基于 vLLM 的 InferenceService 都接受 reasoning_effort。是否支持取决于 vLLM 版本、OpenAI-compatible server 实现、模型以及 chat template。如果服务会拒绝未知请求字段,即使模型本身支持 reasoning,reasoning_effort 仍可能失败。

优先使用你部署的 vLLM 服务文档中定义的模型特定控制方式。例如,Qwen3 风格的 template 通常使用 chat_template_kwargs 来启用或禁用 thinking:

{
  "model": "Qwen/Qwen3-8B",
  "messages": [{"role": "user", "content": "..."}],
  "chat_template_kwargs": {
    "enable_thinking": false
  }
}

使用 OpenAI Python client 时,可通过 extra_body 传递 vLLM 特定的请求字段:

client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[{"role": "user", "content": "..."}],
    extra_body={"chat_template_kwargs": {"enable_thinking": False}},
)

对于支持显式 thinking budget 的 parser,还可以为每个请求限制 reasoning token 数:

{
  "model": "Qwen/Qwen3-0.6B",
  "messages": [{"role": "user", "content": "..."}],
  "thinking_token_budget": 256
}

如果使用翻译代理(LiteLLM 或 claude-code-router),请先确认代理版本会透传这些 vLLM/OpenAI 扩展字段,再依赖它们。

只有在确认你所使用的确切 vLLM 镜像和模型模板支持后,才使用 reasoning_effort。在受支持的部署上,它可以作为顶层 Chat Completions 字段发送,例如 "reasoning_effort": "low";在不受支持的部署上,请改用 chat_template_kwargs、thinking_token_budget 或 max_tokens。

第 3 步:连接你的编码智能体

opencode

opencode 从项目根目录下的 opencode.json 或 ~/.config/opencode/opencode.json 读取配置。定义一个指向你的端点的自定义 OpenAI-compatible provider:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "onprem": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "On-Prem Alauda AI",
      "options": {
        "baseURL": "https://your-inference-service-domain.com/v1",
        "apiKey": "{env:ONPREM_API_KEY}"
      },
      "models": {
        "qwen-2": {
          "name": "Qwen3.6-35B-A3B (on-prem)"
        }
      }
    }
  }
}
  • 模型键(qwen-2)必须与 InferenceService 的 --served-model-name 一致。
  • 导出配置中引用的 key,然后选择该模型:export ONPREM_API_KEY=sk-local,并在 opencode 内使用 /models 命令选择 onprem/qwen-2。

Codex CLI

Codex CLI 读取 ~/.codex/config.toml。将你的端点注册为模型提供方并选中它:

model = "qwen-2"
model_provider = "onprem"

[model_providers.onprem]
name = "On-Prem Alauda AI"
base_url = "https://your-inference-service-domain.com/v1"
env_key = "ONPREM_API_KEY"
wire_api = "chat"
  • base_url 必须以 /v1 结束;model 必须与 --served-model-name 匹配。
  • env_key 指定保存 API key 的环境变量名称:export ONPREM_API_KEY=sk-local。
  • 对于 vLLM 的 OpenAI Chat Completions API,请使用 wire_api = "chat"。

Claude Code

Claude Code 通过 Anthropic Messages API(/v1/messages)通信,而你的 InferenceService 暴露的是 OpenAI-compatible 端点(/v1/chat/completions)。你可以在端点前运行一个翻译代理来桥接两者。常见的两种方案:

  • LiteLLM 代理:暴露一个 Anthropic-compatible 的 /v1/messages 端点,并将请求路由到任意后端模型。
  • claude-code-router:专为将 Claude Code 指向 OpenAI-compatible 及其他后端而构建的代理。

这两种方式都会为你处理 API 翻译。选择最适合你工作流的方案即可——LiteLLM 更通用,而 claude-code-router 更贴合 Claude Code 的需求。

方案 1:LiteLLM 代理

启动 LiteLLM 代理,并将其指向你的 InferenceService 端点:

litellm --model openai/qwen-2 \
  --api_base https://your-inference-service-domain.com/v1 \
  --port 4000

这会暴露 http://localhost:4000/v1/messages(Anthropic format),并将请求转发到你的 OpenAI-compatible 后端。

然后将 Claude Code 指向该代理:

export ANTHROPIC_BASE_URL="http://127.0.0.1:4000"
export ANTHROPIC_AUTH_TOKEN="not_set"
export ANTHROPIC_API_KEY="not_set_either!"
export ANTHROPIC_MODEL="qwen-2"

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export CLAUDE_CODE_ATTRIBUTION_HEADER=0
export CLAUDE_CODE_ENABLE_TELEMETRY=0
export CLAUDE_CODE_DISABLE_1M_CONTEXT=1
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

claude

方案 2:claude-code-router

在 ~/.claude-code-router/config.json 中创建配置文件,并将你的 InferenceService 作为 provider:

{
  "Providers": [
    {
      "name": "onprem",
      "api_base_url": "https://your-inference-service-domain.com/v1/chat/completions",
      "api_key": "sk-local",
      "models": ["qwen-2"]
    }
  ],
  "Router": {
    "default": "onprem,qwen-2"
  }
}

然后通过 router 启动 Claude Code:

ccr code

router 会自动设置所需的 ANTHROPIC_BASE_URL 和其他环境变量——无需手动 export。模型通过配置中的 Router.default 字段选择(格式:provider_name,model_name)。你也可以先在 shell 中执行 eval "$(ccr activate)" 激活 router,然后直接运行 claude。在运行中的会话内,可使用 /model provider_name,model_name 切换模型。

本地部署运行注意事项

  • ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY 的值(LiteLLM 方案会用到)必须非空,但如果你的代理和端点不会检查它们,其内容并不重要;请在端点或代理处进行访问控制(参见 管理 gateway,了解如何通过 Envoy AI Gateway 添加认证)。
  • CLAUDE_CODE_DISABLE_* 标志才是真正把“on-prem”方案留在本地的关键:如果没有这些标志,Claude Code 仍可能向 Anthropic 托管端点发出非必要请求,并向模型请求本地模型无法满足的功能(1M context、超大输出)。claude-code-router 会自动设置其中一部分。
  • ANTHROPIC_MODEL 必须与 InferenceService 暴露的模型名称一致(即 --served-model-name)。
  • 你还可以选择将 ANTHROPIC_SMALL_FAST_MODEL 设置为本地模型,这样后台/低成本请求也会保持在本地。

Claude Code 的 agentic 质量在很大程度上取决于所提供模型的 tool-calling 可靠性——请优先选择指令遵循能力强、经过 tool 调优的模型,并在依赖它之前先验证 tool call 能够端到端往返。

最佳实践

作为最佳实践,请基于以下五个模型系列来构建本地部署的编码智能体——并且为了让结果更可预测,把它们当作首选清单,而不是去寻找其他模型。每个模型都兼具强大的代码生成能力、可靠的指令遵循能力和原生 tool/function calling,并且都提供不同尺寸和量化格式,便于适配你现有的加速器。为每个选择搭配与硬件匹配的量化版本:GPU 上使用 Unsloth GGUF 构建,或者在 Ascend NPU 上使用 ModelSlim (msModelSlim) W8A8/W4A8 构建(参见 适配硬件的量化版本)。

模型类型适用于编码智能体的原因适配与说明
GLM-5.2 (Zhipu AI)大型 MoE具备前沿级 agentic reasoning 和多步工具使用能力;擅长跨多个文件的长篇、计划性修改。该组中最重——应使用量化版(GGUF / ModelSlim)或跨多个加速器做 tensor-parallel 服务。
Qwen3.6-27B-MTP (Qwen)稠密 qwen3_5 混合 + MTP通用编码能力强;原生 multi-token-prediction 头可加速 decode,让交互轮次更迅捷。在 Ascend 上已验证 W8A8 → Qwen3.6-27B (W8A8)。约 33–36 GB 量化后体积。
Qwen3.6-35B-A3B (Qwen)MoE,约 3B 激活参数该组中性价比最高:每个 token 仅激活约 3B 参数,却保留 35B 级别知识库。在单张 24 GB GPU 上也能较轻松运行——推荐大多数用户默认使用。
Gemma4-12B-it / Gemma4-31B-it (Google)稠密,instruction-tuned指令遵循干净,tool call 可靠。12B 适合中端 GPU;31B 在 40–48 GB 卡上可带来更高质量。追求延迟请选择 12B,追求质量请选择 31B。
Deepseek-v4 (DeepSeek)大型 MoE(MLA + DSA + MTP)前沿级编码与 agentic planning;稀疏 MoE 在拥有庞大 expert 池的同时保持较低的激活参数。重型模型——请使用量化版或多 GPU/多卡部署。在 Ascend 上已验证 W4A8 → DeepSeek-V4-Flash (W4A8)。

请根据你所运行的 vLLM 版本,确认匹配的 vLLM --tool-call-parser(对于具备 reasoning 能力的系列,还要确认 --reasoning-parser)——参见 在运行时启用 tool calling。

选择适合硬件的模型

先从你已有的 GPU 显存出发,再选择最大且仍能为 KV cache 留出余量的模型。一个粗略的权重大小估算公式是 parameters × bytes-per-parameter——FP16 约 2 字节,FP8/INT8 约 1 字节,INT4 约 0.5 字节/参数——除此之外,KV cache 和运行时开销还会消耗更多显存。请保留 15–25% 的余量。

适配硬件的量化版本

Alauda AI 所运行的加速器可由两条量化路径覆盖。选择与你硬件匹配的构建,然后应用上面的 15–25% 余量规则。

GPU — Unsloth GGUF。 Unsloth 提供最新模型的 GGUF 构建,针对使用 vLLM 快速加载进行了优化(--quantization gguf)。其 QAT(quantization-aware training)构建在激进 bit-width 下比后量化更能保持质量。对于推荐模型,最实用的构建如下:

模型格式激活参数VRAM(约)说明
unsloth/gemma-4-12b-it-GGUFGGUF12B~16 GB可放入单张中端 GPU
unsloth/Qwen3.6-35B-A3B-GGUFGGUF (MoE)~3B 激活~12 GB性价比最高;可放入 24 GB
unsloth/Qwen3.6-27B-MTP-GGUFGGUF (MTP)27B~36 GBMulti-token prediction,可更快 decode
unsloth/gemma-4-31b-it-GGUFGGUF31B~40 GB质量最高的稠密 Gemma 4
unsloth/GLM-5.2-GGUFGGUF (MoE)largemulti-GPU前沿 agentic;使用 --tensor-parallel-size 分片
unsloth/Deepseek-v4-GGUFGGUF (MoE)largemulti-GPU前沿编码;跨 GPU 分片

注意: Unsloth 仓库名称遵循 unsloth/<model>-GGUF 约定——在拉取前请确认 Unsloth 组织页面 上的准确路径,尤其是大型 GLM-5.2 和 Deepseek-v4 构建,它们通常会拆分为多个文件。如果你想使用 AWQ 或 GPTQ INT4 变体,可以在 huggingface.co/models 上搜索,例如 qwen3.6 AWQ 或 gemma-4 GPTQ。

Ascend NPU — ModelSlim (msModelSlim)。 在华为 Ascend NPU 上,可使用 Ascend 的 msModelSlim 工具包进行量化,它会生成可通过 Alauda AI 的 InferNex 接口在 vLLM-Ascend 引擎上提供服务的 W8A8 / W4A8 权重。推荐模型中已有两个以经过验证、基准测试的 recipe 形式提供:

模型ModelSlim 格式拓扑Recipe
Qwen3.6-27BW8A8 (~33 GB)Ascend 910B4 ×8 (2 × TP=4)Qwen3.6-27B (W8A8)
DeepSeek-V4-FlashW4A8 (~151 GB)Ascend 910B4 ×8 (1 × TP=8)DeepSeek-V4-Flash (W4A8)

若要在 NPU 上量化你自己的权重,请使用 ModelSlim workbench 镜像及其验证 notebook(参见 创建 Workbench)。

硬件适配指南

加速器显存示例硬件推荐模型
12–16 GBL4, A10, RTX 4070Qwen3.6-35B-A3B(MoE,约 3B 激活)或 Gemma4-12B-it
24 GBA30 (24G), RTX 4090Qwen3.6-35B-A3B(MoE)——推荐默认值
40–48 GBA40, L40S, A6000Qwen3.6-27B-MTP 或 Gemma4-31B-it(GGUF)
80 GBA100-80G, H100, H800Qwen3.6-27B-MTP 或 FP16 的 Gemma4-31B-it
Ascend NPU(8 × 32 GB)Ascend 910B4 ×8Qwen3.6-27B(W8A8)或 Deepseek-v4(W4A8),ModelSlim —— 参见 推理指南
Multi-GPU / multi-card (2–8×)2–8 × 80 GBGLM-5.2 或 Deepseek-v4(大型 MoE,tensor-parallel)

补充选择建议:

  • 保持在这五个推荐系列之内。 它们都经过 instruction-tuned,并且原生支持 tool/function calling——这是智能体可靠编辑文件的前提。偏离到模型卡未提及 tool calling 的模型,通常意味着智能体可以聊天但无法执行操作。
  • 确认你选择的模型存在匹配的 vLLM parser(参见 在运行时启用 tool calling)后再决定采用它。请在你所用版本的 vLLM 文档中验证 --tool-call-parser(以及 reasoning-capable 的 GLM-5.2、Qwen3.6 和 Deepseek-v4 所需的 --reasoning-parser)。
  • 为上下文长度预留预算。 编码智能体会发送大 prompt(system prompt + 文件和仓库上下文)。选择一个其上下文窗口足以覆盖你预期最大 prompt 的模型,并记住更长的 --max-model-len 会为每个请求消耗更多 KV cache,降低并发能力。
  • 量化在本地部署中具有放大效应。 GGUF(GPU,通过 Unsloth)或 W8A8/W4A8(Ascend NPU,通过 ModelSlim)可以让你在相同显存中放入明显更强的模型,而这通常比原始 FP16 精度对智能体质量更重要。
  • MoE 模型尤其高效。 Qwen3.6-35B-A3B、GLM-5.2 和 Deepseek-v4 在每个 token 上只激活其一部分参数,却保留更大的知识库,以较低的 VRAM 成本提供接近稠密模型的质量。

调优推理服务性能

编码智能体流量具有鲜明特征:长且高度重复的 prompt(相同的 system prompt 和仓库上下文会在每轮重复发送)、短交互请求的突发流量,以及对首 token 延迟的敏感性。请针对这些特点进行调优:

  • 启用 prefix caching(--enable-prefix-caching)。这是对编码智能体影响最大的单项参数:共享的 prompt 前缀在多轮之间会被复用,而不是重复计算,从而显著降低 prefill 成本和延迟。参见 Automatic Prefix Caching — vLLM。
  • 将 --gpu-memory-utilization 提高到 0.90–0.95,以增大 KV cache,从而提升并发能力和可维持的上下文长度。
  • 合理设置 --max-model-len。 将其设置为智能体实际所需的最大上下文,而不是模型理论最大值——每增加一个 token 的容量都会占用 KV cache 显存。
  • 当长 prompt 在高并发下造成延迟尖峰时,启用 chunked prefill(--enable-chunked-prefill),以避免 decode 步骤被大规模 prefill 饿死。注意 CLI 示例 默认关闭它。
  • 允许 CUDA graphs 以获得稳定态延迟: CLI 示例设置了 ENFORCE_EAGER=True(eager mode,启动更快但运行更慢)。服务稳定后,切换到非 eager 以捕获 CUDA graphs,但启动时间会更长。
  • 使用 --max-num-seqs 和 --max-num-batched-tokens 调整 batching,在你的并发级别下平衡吞吐量与单请求延迟。
  • 在显存紧张时使用 FP8 KV cache(--kv-cache-dtype fp8),以延长上下文长度并提高并发。
  • 当模型无法装入单卡时,使用 --tensor-parallel-size 将大模型分片到多张 GPU 上。
  • 为 agent 循环启用 MTP / speculative decoding 以降低交互延迟——推荐的 Qwen3.6-27B-MTP 和 Deepseek-v4 都自带原生 multi-token-prediction 头。参见下文 启用 MTP(multi-token prediction) 以及 vLLM 推理服务的 Speculative Decoding。
  • 注意 autoscaling 和冷启动。 对于交互式单用户智能体场景,请保持 minReplicas: 1——从 0 扩容会增加数分钟的冷启动,在任务进行中会非常痛苦。对于突发式多开发人员使用,请有意识地配置 autoscaling;参见 为推理服务配置扩缩容 和 使用 KEDA 为推理服务设置自动扩缩容。
  • 允许长请求。 智能体轮次可能运行较长;请相应调整 Knative 的 serving.knative.dev/progress-deadline 注解和客户端超时。如果请求被截断,参见 推理超时故障排查。

启用 MTP(multi-token prediction)

两个推荐模型——Qwen3.6-27B-MTP 和 Deepseek-v4——自带原生 multi-token-prediction (MTP) 头,可在每个 decode step 中提议多个 token,从而降低智能体循环中的交互延迟,而无需单独管理 draft model。MTP 是一种 speculative decoding,需通过运行时的 speculative-decoding 配置启用。

vLLM。 将模型的 MTP method 传给 --speculative-config。method 字符串和 token 数因模型和版本而异;以下值来自经过验证的 recipe:

# Qwen3.6-27B-MTP (qwen3_5 architecture)
--speculative-config '{"method":"qwen3_5_mtp","num_speculative_tokens":3}'

# Deepseek-v4
--speculative-config '{"method":"mtp","num_speculative_tokens":1}'

请根据你所使用的 vLLM 版本确认准确的 method,并将完整 recipe 视为事实依据——包括这些在 Ascend 上需要的 MTP guardrail(禁用 prefix caching、限制 --max-num-seqs、enforce_eager):Qwen3.6-27B (W8A8) 和 DeepSeek-V4-Flash (W4A8)。关于其他 speculative 方法(EAGLE-3、N-gram)以及端到端验证与回滚,请参见 vLLM 推理服务的 Speculative Decoding。

llama.cpp(GGUF)。 在提供支持 MTP 的 GGUF 构建(例如 Unsloth 的 -MTP 权重)时,使用 --spec-type draft-mtp 开启 draft-MTP 路径。请根据你的 llama.cpp 构建验证该参数——不同版本对 MTP 的支持和参数名会变化。

NOTE

MTP 加速的是 decode,不是 prefill,其收益取决于你的流量对 proposal 的接受率。在正式采用前,请在具有代表性的编码智能体工作负载上进行开启与关闭对比测试,并测量真实的每 token 延迟(ITL):MTP step 在每个流式 chunk 中会发出多个 token,因此 chunk 级延迟会低估单 token 的收益。对于上面的 Ascend 方案,W8A8/W4A8 量化会为更大的 KV cache 释放 HBM,但本身并不会加速 MTP decode 路径。

从 vibe coding 开始上手

“vibe coding”——通过描述意图并让智能体编写代码来快速迭代——在自托管模型基础设施准备充分后表现很好:

  1. 从一个在你的 GPU 上有充足余量、且运行顺畅的推荐模型开始——Qwen3.6-35B-A3B 或 Gemma4-12B-it 是很好的起点;一个响应更快的小模型通常比一个迟缓的大模型更适合交互式流程。对于 24 GB GPU,Qwen3.6-35B-A3B(MoE,约 3B 激活)是极好的起点。
  2. 为代码生成设置 较低的 temperature(大约 0–0.2),以保持修改确定性并减少反复试探。
  3. 在尝试任何真实任务之前,先用一个简单任务验证 tool calling(例如“创建一个文件并运行它”)。
  4. 保持 prompt 聚焦——只打开或引用相关文件,这样智能体上下文就能保持在主题上,同时 prefill 成本也更低。
  5. 采用小而可审查的步骤,并在接受每个 diff 之前阅读它。频繁提交,这样就能干净地回滚错误建议。

从 MLOps 开始上手

由于模型运行在你的集群内部,因此由本地部署 InferenceService 支持的编码智能体非常适合用于平台本身的运维——你的 manifests、configs 和专有代码不会离开环境,这在受监管场景中尤其重要。适合的起始任务包括:

  • 生成或修改 InferenceService YAML——例如:“为模型 X 编写一个面向 24 GB GPU 的 InferenceService,启用 prefix caching 和 tool calling。”
  • 添加 autoscaling、调度或资源配置——例如 KEDA/KPA 自动扩缩容、支持 CUDA 版本感知的调度,或 Kueue/Volcano 队列管理。
  • 为模型生命周期编写和调整流水线与监控。
  • 形成闭环:用智能体部署一个模型,然后再使用同一个本地部署模型驱动进一步的平台运维操作。

关于详细的 MLOps 工作流——管理 InferenceServices、配置 gateway、迭代调优性能以及规划 fine-tuning 任务——请参见 使用编码智能体和本地部署 LLM 运行 MLOps。

故障排查

  • 智能体能聊天,但从不编辑文件或运行命令。 没有启用 tool calling,或者 parser 与模型不匹配——参见 在运行时启用 tool calling。
  • model not found / 404。 智能体配置中的模型名称与 --served-model-name 不匹配,或者 base URL 不以 /v1 结尾。
  • 401 / 403。 智能体发送了错误的 API key,或者没有发送,而端点或 gateway 需要不同的值。
  • 长任务请求超时。 增加 Knative 的 progress-deadline 注解和客户端超时——参见 推理超时故障排查。
  • 空闲后的第一次请求非常慢。 服务已缩容到 0 并正在冷启动;对于交互式使用,请设置 minReplicas: 1。

参考资料