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

简介

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

本文介绍如何将这些智能体指向您在 Alauda AI Platform 上自行提供的模型,使您的源代码、提示词和基础设施配置始终留在集群中。您为其他工作负载部署的相同本地部署 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 endpoint(请参阅 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 endpoint 前面配置一个小型转换代理(请参阅 Claude Code)。

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

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

在连接任何智能体之前,请确认端点可以响应聊天请求。如果基础 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 表明端点可访问且模型名称正确。请记下每个智能体都会重复使用的三个值:基础 URL(以 /v1 结尾)、模型名称(即 --served-model-name)和 API key。

TIP

对于支持推理的模型(推荐集合中的 GLM-5.2 和 Qwen3.6,以及支持推理模式的 Deepseek-v4 构建版本),还应将匹配的 --reasoning-parser 添加到 vLLM 启动标志中。请参阅配置推理模型和推理工作量。

步骤 2:在运行时启用工具调用

编码智能体通过调用工具来工作(读取文件、写入文件、运行 shell)。这要求模型生成工具调用,并且 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
  • 解析器必须与模型匹配。例如,Qwen2.5 和 QwQ-32B 通常使用 hermes;Qwen3-Coder 使用 qwen3_xml;Llama 3.x 模型使用 llama3_json;Mistral 模型使用 mistral。请查看 vLLM 工具调用文档,了解当前的解析器列表以及与您的模型匹配的值。
  • 某些模型需要特定的聊天模板才能正确生成工具调用;如果模型卡要求,请传递 --chat-template。
  • 如果提供的是推理模型,还应启用匹配的 --reasoning-parser,以便智能体接收与推理轨迹分离的干净助手内容。

请让智能体执行简单的文件操作(例如,创建包含单词 hi 的 hello.txt),以端到端验证工具调用。如果模型以文本回复而不是编辑文件,则说明工具调用未正确连接——请重新检查解析器和模型。

步骤 2b(可选):配置推理模型和推理工作量

某些模型会在最终答案之前输出思维链推理。在推荐的模型系列中,这包括 GLM-5.2 和 Qwen3.6(默认启用推理),以及推理模式的 Deepseek-v4 构建版本。vLLM 会将推理轨迹与助手内容分离,使您的智能体接收到干净的输出——但您必须启用匹配的标志。

服务端标志

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

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

下表列出了用于参考的解析器组合。解析器名称与版本相关,并且会随着 vLLM 版本的发布而变化——请始终根据您运行版本的 vLLM 工具调用文档进行确认。

模型系列--tool-call-parser--reasoning-parser备注
Qwen3 / Qwen3.6 推理(Qwen/Qwen3*)请查看当前 vLLM 文档,确认确切的 Qwen 变体qwen3默认启用推理;如有需要,可使用 chat_template_kwargs 禁用推理
GLM-5.2(Zhipu AI)请查看当前 vLLM 文档,确认 GLM 变体请查看当前 vLLM 文档,确认 GLM 变体混合推理;工具调用解析器和推理解析器共享 GLM 系列值
Deepseek-v4(deepseek_v4)请查看当前 vLLM 文档,确认 DeepSeek 变体请查看当前 vLLM 文档,确认 DeepSeek 变体仅适用于推理模式构建版本;请参阅 DeepSeek-V4-Flash (W4A8) 配方

这些模型系列的确切 --tool-call-parser / --reasoning-parser 值取决于 vLLM 版本——在确定配置前,请阅读模型卡和 vLLM 工具调用文档,并验证工具调用是否能够端到端往返。

配置推理工作量和思考行为

推理工作量控制模型在回答前进行多少“思考”。对于编码智能体,通常应使用较低的推理工作量,以确保交互延迟处于可接受范围——许多次简短的低推理工作量交互,通常优于一次漫长的高推理工作量交互。

服务端默认值

vLLM 不提供通用的 --reasoning-effort 启动标志。可以通过模型的聊天模板实现服务范围的控制:提供一个默认禁用思考的自定义 Jinja 模板,然后使用 --chat-template 传递该模板。或者,某些模型和 vLLM 版本会提供针对每个模型的模板 kwargs;请查看 vLLM release notes,了解具体键名。

请求时控制

不要假设每个基于 vLLM 的 InferenceService 都接受 reasoning_effort。是否支持取决于 vLLM 版本、兼容 OpenAI 的服务器实现、模型和聊天模板。如果服务拒绝未知请求字段,即使模型本身支持推理,reasoning_effort 也可能失败。

优先使用已部署的 vLLM 服务文档中说明的模型专属控制项。例如,Qwen3 风格的模板通常使用 chat_template_kwargs 来启用或禁用思考:

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

使用 OpenAI Python 客户端时,请通过 extra_body 传递 vLLM 专属的请求字段:

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

对于支持显式思考预算的解析器,还可以限制每个请求的推理令牌数:

{
  "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 兼容提供程序:

{
  "$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 密钥的环境变量: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 兼容端点(/v1/chat/completions)。在端点前运行转换代理,以桥接两者。常见的选项有:

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

这两种方案都会为你处理 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 兼容后端。

然后将 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 设为提供程序:

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

然后通过路由器启动 Claude Code:

ccr code

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

本地部署注意事项

  • ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY 的值(LiteLLM 选项中使用)必须非空;但如果你的代理和端点不检查其内容,具体内容并不重要。请在端点或代理处控制访问权限(有关通过 Alauda AI Platform Gateway 添加身份验证,请参阅管理网关)。
  • CLAUDE_CODE_DISABLE_* 标志才是真正确保“本地部署”始终留在本地的关键:如果不设置这些标志,Claude Code 仍可能向 Anthropic 托管的端点发送非必要请求,并向模型请求本地模型无法支持的功能(100 万上下文、极大输出)。claude-code-router 会自动设置其中一些标志。
  • ANTHROPIC_MODEL 必须与 InferenceService 暴露的模型名称相匹配(即 --served-model-name)。
  • 你也可以选择将 ANTHROPIC_SMALL_FAST_MODEL 设置为本地模型,以便后台请求和低成本请求也留在本地。

Claude Code 的智能体能力很大程度上取决于所提供模型的工具调用可靠性。请优先选择指令遵循和工具调用调优能力强的模型,并在依赖该模型之前,确认工具调用的整个往返流程端到端正常。

最佳实践

作为最佳实践,请基于以下五个模型系列构建本地部署的编码智能体;为确保结果可预测,应将它们视为候选清单,而不是转向其他模型。每个模型系列都兼具出色的代码生成能力、可靠的指令遵循能力以及原生工具/函数调用能力,并提供多种大小和量化格式,便于根据现有加速器进行适配。每次选择都应搭配与硬件匹配的量化版本:GPU 上使用 Unsloth GGUF 构建,Ascend NPU 上使用 ModelSlim(msModelSlim) W8A8/W4A8 构建(请参阅适配硬件的量化变体)。

模型类型适用于编码智能体的原因适配性和注意事项
GLM-5.2(Zhipu AI)大型 MoE前沿的智能体推理和多步工具使用能力;擅长跨多个文件执行长期规划的编辑操作。该系列中最占资源的模型 — 请使用量化版本(GGUF / ModelSlim),或在多个加速器之间进行张量并行。
Qwen3.6-27B-MTP(Qwen)Dense qwen3_5 混合模型 + MTP通用代码能力强;原生多令牌预测头可加快解码,使交互响应更加迅速。Ascend 上已验证 W8A8 → Qwen3.6-27B (W8A8)。量化后约占用 ~33–36 GB。
Qwen3.6-35B-A3B(Qwen)MoE,约 ~3B 个激活参数该系列中单位 VRAM 的质量最佳:每个令牌仅激活约 ~3B 个参数,同时保留 35B 的知识库。可在单个 24 GB GPU 上轻松运行 — 对大多数用户而言是推荐的默认选择。
Gemma4-12B-it / Gemma4-31B-it(Google)Dense、经过指令调优指令遵循清晰可靠,工具调用稳定。12B 适合中端 GPU;31B 可在 40–48 GB 卡上提升质量。延迟优先选择 12B,质量优先选择 31B。
Deepseek-v4(DeepSeek)大型 MoE(MLA + DSA + MTP)前沿级代码能力和智能体规划能力;稀疏 MoE 在拥有大量专家的同时保持较少的激活参数。占用资源较多 — 请使用量化版本或多 GPU/多卡部署。Ascend 上已验证 W4A8 → DeepSeek-V4-Flash (W4A8)。

请根据所运行的 vLLM 版本确认对应的 vLLM --tool-call-parser(对于支持推理的模型系列,还需确认 --reasoning-parser)— 请参阅在运行时启用工具调用。

选择适配硬件的模型

首先根据可用的 GPU 内存进行判断,然后选择能够留出 KV cache 余量的最大可用模型。粗略的权重大小估算公式为 parameters × bytes-per-parameter — FP16 约为每个参数 2 字节,FP8/INT8 约为每个参数 1 字节,INT4 约为每个参数 0.5 字节 — 此外,KV cache 和运行时开销还会消耗更多内存。请预留 15–25% 的余量。

适配硬件的量化变体

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

GPU — Unsloth GGUF。 Unsloth 发布了最新模型的 GGUF 构建,针对使用 vLLM(--quantization gguf)进行快速加载进行了优化。其 QAT(量化感知训练)构建在激进位宽下比事后量化更能保持模型质量。对于推荐模型,最实用的构建如下:

模型格式激活参数VRAM(约)注意事项
unsloth/gemma-4-12b-it-GGUFGGUF12B~16 GB可在单个中端 GPU 上运行
unsloth/Qwen3.6-35B-A3B-GGUFGGUF (MoE)~3B 激活~12 GB质量/VRAM 比最佳;适合 24 GB
unsloth/Qwen3.6-27B-MTP-GGUFGGUF (MTP)27B~36 GB使用多令牌预测加快解码
unsloth/gemma-4-31b-it-GGUFGGUF31B~40 GB质量最高的 Dense Gemma 4
unsloth/GLM-5.2-GGUFGGUF (MoE)大型多 GPU前沿智能体能力;使用 --tensor-parallel-size 进行分片
unsloth/Deepseek-v4-GGUFGGUF (MoE)大型多 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)。 在 Huawei Ascend NPU 上,请使用 Ascend 的 msModelSlim 工具包进行量化,该工具包会生成 W8A8 / W4A8 权重,并通过 Alauda AI Platform 的 InferNex 界面在 vLLM-Ascend 引擎上提供服务。推荐的两个模型已经提供经过验证和基准测试的配置方案:

模型ModelSlim 格式拓扑配置方案
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、H800FP16 下使用 Qwen3.6-27B-MTP 或 Gemma4-31B-it
Ascend NPU(8 × 32 GB)Ascend 910B4 ×8Qwen3.6-27B(W8A8)或 Deepseek-v4(W4A8)、ModelSlim — 请参阅已验证模型
多 GPU / 多卡(2–8×)2–8 × 80 GBGLM-5.2 或 Deepseek-v4(大型 MoE,张量并行)

其他选择建议:

  • 限定在五个推荐模型系列内。 它们都经过指令调优,并原生支持工具/函数调用 — 这是智能体可靠编辑文件的前提。如果转而使用模型卡未提及工具调用的模型,通常意味着智能体只能聊天而无法执行操作。
  • 在确定模型之前,确认存在匹配的 vLLM 解析器(请参阅在运行时启用工具调用)。根据所用版本,在 vLLM 文档中验证 --tool-call-parser(对于支持推理的 GLM-5.2、Qwen3.6 和 Deepseek-v4,还需验证 --reasoning-parser)。
  • 为上下文长度预留资源。 编码智能体会发送较大的提示(系统提示 + 文件和仓库上下文)。请选择上下文窗口能够覆盖最大预期提示的模型,并记住,较长的 --max-model-len 会为每个请求消耗更多 KV cache,从而降低并发能力。
  • 量化是本地部署中的性能倍增器。 GGUF(GPU,通过 Unsloth)或 W8A8/W4A8(Ascend NPU,通过 ModelSlim)可以让你在相同内存中容纳明显更强的模型;对于智能体质量而言,这通常比原始 FP16 精度更重要。
  • MoE 模型尤其高效。 Qwen3.6-35B-A3B、GLM-5.2 和 Deepseek-v4 每个令牌只激活一部分参数,同时保留更大的知识库,以极低的 VRAM 成本提供接近 Dense 模型的质量。

调优推理服务性能

编码智能体流量具有独特特征:较长且高度重复的提示(每轮都会重新发送相同的系统提示和仓库上下文)、短时的交互式请求突发,以及对首令牌延迟的敏感性。请针对这些特征进行调优:

  • 启用前缀缓存(--enable-prefix-caching)。这是对编码智能体影响最大的单项标志:跨轮次复用共享提示前缀,而不是重新计算,从而大幅降低预填充成本和延迟。请参阅 Automatic Prefix Caching — vLLM。
  • 将 --gpu-memory-utilization 提高到接近 0.90–0.95,以扩大 KV cache,从而提高并发能力和可持续的上下文长度。
  • 合理设置 --max-model-len。 将其设为智能体实际需要的最大上下文,而不是模型的理论最大值 — 容量的每个额外令牌都会消耗 KV cache 内存。
  • 当长提示在并发场景下造成延迟峰值时,启用分块预填充(--enable-chunked-prefill),避免大型预填充过程使解码步骤得不到资源。请注意,CLI 示例默认将其禁用。
  • 允许使用 CUDA graphs 以获得稳定的延迟:CLI 示例设置了 ENFORCE_EAGER=True(eager 模式,启动更快但运行更慢)。服务稳定后,切换到非 eager 模式以捕获 CUDA graphs,但启动时间会更长。
  • 使用 --max-num-seqs 和 --max-num-batched-tokens 调优批处理,根据并发级别平衡吞吐量与单请求延迟。
  • 使用 FP8 KV cache(--kv-cache-dtype fp8),在内存紧张时延长上下文长度并提高并发能力。
  • 当模型无法容纳在单张卡上时,使用 --tensor-parallel-size 跨 GPU 对大型模型进行分片。
  • 启用 MTP / speculative decoding,降低智能体循环中的交互延迟 — 推荐的 Qwen3.6-27B-MTP 和 Deepseek-v4 都提供原生多令牌预测头。请参阅下方的启用 MTP(多令牌预测)以及适用于 vLLM 推理服务的 Speculative Decoding。
  • 注意自动扩缩容和冷启动。 对于交互式单用户智能体使用场景,请保持 minReplicas: 1 — 从零扩容会增加数分钟的冷启动时间,在任务中途会造成严重影响。对于突发式的多开发人员使用场景,请有意配置自动扩缩容;请参阅为推理服务配置扩缩容和使用 KEDA 设置推理服务自动扩缩容。
  • 允许长时间运行的请求。 智能体轮次可能运行较长时间;请相应设置 Knative serving.knative.dev/progress-deadline 注解和客户端超时。如果请求被截断,请参阅推理超时故障排除。

启用 MTP(多令牌预测)

推荐模型中的两个模型 — Qwen3.6-27B-MTP 和 Deepseek-v4 — 提供原生 多令牌预测(MTP) 头,可在每个解码步骤中预测多个令牌,从而降低智能体循环中的交互延迟,并且无需管理单独的草稿模型。MTP 是 speculative decoding 的一种形式,通过运行时的 speculative-decoding 配置启用。

vLLM。 将模型的 MTP 方法传递给 --speculative-config。method 字符串和令牌数量因模型和版本而异;以下是经过验证的配置方案中的值:

# 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,并将完整配置方案(包括 Ascend 上所需的 MTP 保护设置:禁用前缀缓存、限制 --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 加速的是解码而不是预填充,其收益取决于流量中的预测接受率。在确定启用之前,请在具有代表性的编码智能体工作负载上分别进行启用和禁用 MTP 的基准测试,并测量实际的每令牌延迟(ITL):MTP 步骤会在每个流式块中输出多个令牌,因此块级延迟会低估每令牌收益。在上述 Ascend 配置中,W8A8/W4A8 量化为更大的 KV cache 释放了 HBM,但不会直接加快 MTP 解码路径。

开始使用 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. 在尝试实际任务之前,先使用一个简单任务(“创建文件并运行它”)验证工具调用。
  4. 保持提示聚焦 — 仅打开或引用相关文件,使智能体上下文保持主题一致,并降低预填充成本。
  5. 分解为较小且易于审查的步骤,并在接受每次修改前阅读 diff。经常提交,以便干净地回滚错误建议。

开始使用 MLOps

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

  • 生成或修改 InferenceService YAML — 例如,“为模型 X 编写一个针对 24 GB GPU,并启用前缀缓存和工具调用的 InferenceService”。
  • 添加自动扩缩容、调度或资源配置 — KEDA/KPA 自动扩缩容、感知 CUDA 版本的调度,或 Kueue/Volcano 排队。
  • 为模型生命周期编写和调整流水线及监控。
  • 形成闭环:使用智能体部署模型,然后使用同一个本地部署模型驱动后续的平台操作。

有关详细的 MLOps 工作流 — 管理 InferenceServices、配置网关、迭代调优性能,以及规划微调任务 — 请参阅 使用 Coding Agents 和本地部署 LLM 运行 MLOps。

故障排除

  • 智能体可以聊天,但从不编辑文件或运行命令。 未启用工具调用,或解析器与模型不匹配 — 请参阅在运行时启用工具调用。
  • model not found / 404。 智能体配置中的模型名称与 --served-model-name 不匹配,或基础 URL 不以 /v1 结尾。
  • 401 / 403。 智能体发送的 API key 不正确(或未发送 API key),不符合端点或网关的要求。
  • 长任务中的请求超时。 增大 Knative progress-deadline 注解值和客户端超时时间 — 请参阅Inference 超时故障排除。
  • 空闲后首次请求非常慢。 服务已缩容至零,正在冷启动;对于交互式使用,请设置 minReplicas: 1。

参考资料