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

简介

opencode(opencode)、Codex CLIClaude Code 这类编码智能体是基于终端的助手,它们会读取你的仓库、规划变更、编辑文件,并代表你运行命令。它们通常通过互联网与托管的模型提供商通信。

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

本页直接建立在部署操作指南之上。它不会重复如何创建或暴露 InferenceService;而是链接到相关内容,并重点介绍面向智能体的配置与调优。

WARNING

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

前提条件

  • 一个正在运行且就绪的 InferenceService,提供 OpenAI-compatible API。参见 使用 CLI 创建 Inference Service
  • 运行智能体的机器可访问该服务端点的网络。如果智能体运行在集群外的开发者笔记本上,请参见 为 Inference Services 配置外部访问
  • 一个支持 tool/function calling 的模型,并使用匹配的 vLLM parser 提供服务(参见 在运行时启用 tool calling)。如果没有这个能力,智能体可以聊天,但不能编辑文件或运行命令。
  • 本地已安装智能体 CLI(opencodecodexclaude)。
  • 对于 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
  • opencodeCodex CLI 原生支持 OpenAI Chat Completions API,因此可以直接调用 InferenceService 端点。
  • Claude Code 使用 Anthropic Messages API,而 vLLM 不提供该 API。它需要在 OpenAI-compatible 端点前面放置一个小型转换代理(参见 Claude Code)。

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

按照 使用 CLI 创建 Inference Service 部署你的模型为 InferenceService;如果智能体运行在集群外,则按照 为 Inference Services 配置外部访问 暴露该服务。

在接入任何智能体之前,先确认端点可以响应聊天请求。如果 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 结尾)、model name--served-model-name)以及 API key

TIP

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

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

编码智能体通过调用工具(读取文件、写入文件、运行 shell)来工作。这要求模型既要输出 tool calls,vLLM 也要能够解析它们。将以下参数添加到 InferenceService 中的 vLLM 启动命令里(在 使用 CLI 创建 Inference Service 的示例中,它们添加在 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 calls;如果模型卡有要求,请传入 --chat-template
  • 如果你提供的是 reasoning model,也要启用匹配的 --reasoning-parser,这样智能体收到的 assistant content 就会与 reasoning traces 分离并保持干净。

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

步骤 2b(可选):配置 reasoning models 和 reasoning effort

有些模型会先输出 chain-of-thought reasoning,再给出最终答案。在推荐的模型家族中,这包括 GLM-5.2Qwen3.6(reasoning 默认开启),以及 reasoning-mode 的 Deepseek-v4 构建。vLLM 会把 reasoning traces 与 assistant content 分离,这样你的智能体就能收到干净的输出——但你必须启用匹配的参数。

服务端参数

--reasoning-parser 添加到你的 vLLM 启动命令中。如果同一个模型还需要 agent tool calls,则将其与合适的 --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 变体混合 reasoning;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 calls 是否能够往返正常。

配置 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 服务端实现、模型以及 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_kwargsthinking_token_budgetmax_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 一致。
  • 导出配置中引用的密钥,然后选择该模型: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 格式),并将请求转发到你的 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 选项一起使用)必须非空,但如果你的代理和端点不会检查它们,其内容并不重要;请在端点或代理层面进行访问控制(参见 管理网关,了解如何通过 Envoy AI Gateway 添加认证)。
  • CLAUDE_CODE_DISABLE_* 标志才是真正让“本地部署”保持在本地的关键:如果没有它们,Claude Code 仍可能向 Anthropic 托管端点发出非必要请求,并向模型请求本地模型无法满足的功能(1M 上下文、超大输出等)。claude-code-router 会自动设置其中的一些。
  • ANTHROPIC_MODEL 必须与 InferenceService 暴露的模型名称一致(即 --served-model-name)。
  • 你也可以选择将 ANTHROPIC_SMALL_FAST_MODEL 设置为一个本地部署模型,这样后台/低成本请求也能留在本地。

Claude Code 的 agentic 能力在很大程度上取决于所提供模型的 tool-calling fidelity——优先选择 instruction 和 tool 调优能力强的模型,并在依赖它之前先端到端确认 tool calls 能够正常往返。

最佳实践

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

模型类型为什么适合编码智能体适配性与说明
GLM-5.2(Zhipu AI)大型 MoE前沿级 agentic reasoning 和多步 tool 使用;擅长跨多个文件的大范围、有计划的编辑。该集合中最重——建议使用量化版(GGUF / ModelSlim)或在多个加速器之间进行 tensor parallel。
Qwen3.6-27B-MTP(Qwen)稠密 qwen3_5 hybrid + MTP通用代码能力强;原生 multi-token-prediction head 可加速 decode,使交互轮次更迅捷。在 Ascend 上已验证 W8A8 → Qwen3.6-27B (W8A8)。量化后约 33–36 GB。
Qwen3.6-35B-A3B(Qwen)MoE,约 3B active该集合中 VRAM 性价比最高:每个 token 仅激活约 3B 参数,但保留 35B 的知识库。在单张 24 GB GPU 上即可轻松运行——这是大多数用户的推荐默认选择。
Gemma4-12B-it / Gemma4-31B-it(Google)稠密,instruction-tuned指令遵循干净,tool calls 可靠。12B 适合中端 GPU;31B 可在 40–48 GB 显卡上提升质量。追求延迟选 12B,追求质量选 31B
Deepseek-v4(DeepSeek)大型 MoE(MLA + DSA + MTP)前沿级代码能力和 agentic planning;尽管专家池很大,稀疏 MoE 仍可保持较低的 active parameters。较重——请使用量化版或多 GPU/多卡部署。在 Ascend 上已验证 W4A8 → DeepSeek-V4-Flash (W4A8)

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

选择适配你硬件的模型

先根据你拥有的 GPU 内存来选择,然后挑选在为 KV cache 保留余量后仍能容纳的最大模型。粗略的权重大小估算公式是 parameters × bytes-per-parameter——FP16 约 2 bytes,FP8/INT8 约 1 byte,INT4 约 0.5 bytes/parameter——除此之外,KV cache 和运行时开销还会占用更多内存。请保留 15–25% 的余量

适配你硬件的量化版本

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

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

模型格式Active paramsVRAM(约)说明
unsloth/gemma-4-12b-it-GGUFGGUF12B~16 GB适合单张中端 GPU
unsloth/Qwen3.6-35B-A3B-GGUFGGUF(MoE)~3B active~12 GB质量/VRAM 比例最佳;适合 24 GB
unsloth/Qwen3.6-27B-MTP-GGUFGGUF(MTP)27B~36 GBmulti-token prediction,解码更快
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.2Deepseek-v4 构建,它们通常会拆分为多个文件。如果你需要 AWQ 或 GPTQ INT4 版本,则可以在 huggingface.co/models 中搜索,例如 qwen3.6 AWQgemma-4 GPTQ

Ascend NPU — ModelSlim (msModelSlim)。 在华为 Ascend NPU 上,请使用 Ascend 的 msModelSlim 工具链进行量化,它会生成可通过 Alauda AI 的 InferNex surface 在 vLLM-Ascend engine 上提供服务的 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 active)或 Gemma4-12B-it
24 GBA30(24G), RTX 4090Qwen3.6-35B-A3B(MoE)——推荐默认选择
40–48 GBA40, L40S, A6000Qwen3.6-27B-MTPGemma4-31B-it(GGUF)
80 GBA100-80G, H100, H800Qwen3.6-27B-MTPGemma4-31B-it,FP16
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.2Deepseek-v4(大型 MoE,tensor parallel)

其他选择建议:

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

调优 inference service 性能

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

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

启用 MTP(multi-token prediction)

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

vLLM。 将模型的 MTP method 传给 --speculative-configmethod 字符串和 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 guardrails(关闭 prefix caching、限制 --max-num-seqsenforce_eager)——作为事实来源: Qwen3.6-27B (W8A8)DeepSeek-V4-Flash (W4A8)。关于其他 speculative 方法(EAGLE-3、N-gram)以及端到端验证与回滚,请参见 vLLM Inference Services 的 Speculative Decoding

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

NOTE

MTP 加速的是 decode,而不是 prefill,而且其收益取决于你流量的 proposal acceptance rate。在确定采用之前,请先在具有代表性的编码智能体工作负载上进行有无对比基准测试,并测量真实的每 token 延迟(ITL):MTP 每个 streamed chunk 会输出多个 token,因此按 chunk 统计的延迟会低估每 token 的收益。在上面的 Ascend recipe 中,W8A8/W4A8 量化为更大的 KV cache 释放了 HBM,但本身并不会加速 MTP decode 路径。

开始进行 vibe coding

“Vibe coding”——通过描述意图并让智能体编写代码来快速迭代——在基础设置正确后,与自托管模型配合得很好:

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

开始进行 MLOps

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

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

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

故障排查

  • 智能体可以聊天,但从不编辑文件或运行命令。 Tool calling 未启用,或者 parser 与模型不匹配——参见 在运行时启用 tool calling
  • model not found / 404。 智能体配置中的模型名称与 --served-model-name 不匹配,或者 base URL 没有以 /v1 结尾。
  • 401 / 403。 智能体发送的 API key 与端点或网关期望的不一致(或未发送)。
  • 长任务请求超时。 增大 Knative 的 progress-deadline 注解以及客户端超时——参见 Inference timeout troubleshooting
  • 空闲后的第一次请求非常慢。 服务已缩容到零并正在 cold-start;对于交互式使用,请设置 minReplicas: 1

参考资料