将编码智能体与本地部署的推理服务结合使用
目录
简介前提条件各组件如何协同工作第 1 步:部署并对端点进行冒烟测试第 2 步:在运行时启用 tool calling第 2b 步(可选):配置推理模型和 reasoning effort服务端参数配置 reasoning effort 和 thinking 行为服务端默认值请求级控制第 3 步:连接你的编码智能体opencodeCodex CLIClaude Code方案 1:LiteLLM 代理方案 2:claude-code-router本地部署运行注意事项最佳实践编码智能体推荐模型选择适合硬件的模型适配硬件的量化版本硬件适配指南调优推理服务性能启用 MTP(multi-token prediction)从 vibe coding 开始上手从 MLOps 开始上手故障排查参考资料简介
像 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;而是链接到相关内容,并聚焦于智能体特定的配置和调优。
编码智能体及其配置格式变化很快。下面的配置片段是本文撰写时可用版本的正确起点。请始终对照你所使用智能体的最新上游文档,确认字段名称。
前提条件
- 一个正在运行且就绪的
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,因此可以直接调用
InferenceService端点。 - Claude Code 使用 Anthropic Messages API,而 vLLM 不提供该 API。它需要在 OpenAI-compatible 端点前放置一个小型翻译代理(参见 Claude Code)。
第 1 步:部署并对端点进行冒烟测试
按照 使用 CLI 创建推理服务 将模型部署为 InferenceService;如果智能体运行在集群外,则按照 为推理服务配置外部访问 公开该服务。
在接入任何智能体之前,先确认端点能够响应一次聊天请求。如果 base URL、模型名称或认证配置错误,编码智能体会以令人困惑的方式失败,因此请先用 curl 验证:
正常的 JSON completion 表明端点可达且模型名称正确。请记下后续所有智能体都会复用的三个值:base URL(以 /v1 结尾)、模型名称(--served-model-name)以及 API key。
对于具备推理能力的模型(在推荐集合中,包括 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 那一行):
- 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 配对使用:
下表列出了 parser 配对以供参考。parser 名称与版本相关,并且会随 vLLM 发布而变化——请始终对照你所运行版本的 vLLM tool calling 文档 进行确认。
这些系列的准确 --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:
使用 OpenAI Python client 时,可通过 extra_body 传递 vLLM 特定的请求字段:
对于支持显式 thinking budget 的 parser,还可以为每个请求限制 reasoning token 数:
如果使用翻译代理(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:
- 模型键(
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。将你的端点注册为模型提供方并选中它:
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 端点:
这会暴露 http://localhost:4000/v1/messages(Anthropic format),并将请求转发到你的 OpenAI-compatible 后端。
然后将 Claude Code 指向该代理:
方案 2:claude-code-router
在 ~/.claude-code-router/config.json 中创建配置文件,并将你的 InferenceService 作为 provider:
然后通过 router 启动 Claude 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 构建(参见 适配硬件的量化版本)。
请根据你所运行的 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 下比后量化更能保持质量。对于推荐模型,最实用的构建如下:
注意: 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 形式提供:
若要在 NPU 上量化你自己的权重,请使用 ModelSlim workbench 镜像及其验证 notebook(参见 创建 Workbench)。
硬件适配指南
补充选择建议:
- 保持在这五个推荐系列之内。 它们都经过 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:
请根据你所使用的 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 的支持和参数名会变化。
MTP 加速的是 decode,不是 prefill,其收益取决于你的流量对 proposal 的接受率。在正式采用前,请在具有代表性的编码智能体工作负载上进行开启与关闭对比测试,并测量真实的每 token 延迟(ITL):MTP step 在每个流式 chunk 中会发出多个 token,因此 chunk 级延迟会低估单 token 的收益。对于上面的 Ascend 方案,W8A8/W4A8 量化会为更大的 KV cache 释放 HBM,但本身并不会加速 MTP decode 路径。
从 vibe coding 开始上手
“vibe coding”——通过描述意图并让智能体编写代码来快速迭代——在自托管模型基础设施准备充分后表现很好:
- 从一个在你的 GPU 上有充足余量、且运行顺畅的推荐模型开始——
Qwen3.6-35B-A3B或Gemma4-12B-it是很好的起点;一个响应更快的小模型通常比一个迟缓的大模型更适合交互式流程。对于 24 GB GPU,Qwen3.6-35B-A3B(MoE,约 3B 激活)是极好的起点。 - 为代码生成设置 较低的 temperature(大约
0–0.2),以保持修改确定性并减少反复试探。 - 在尝试任何真实任务之前,先用一个简单任务验证 tool calling(例如“创建一个文件并运行它”)。
- 保持 prompt 聚焦——只打开或引用相关文件,这样智能体上下文就能保持在主题上,同时 prefill 成本也更低。
- 采用小而可审查的步骤,并在接受每个 diff 之前阅读它。频繁提交,这样就能干净地回滚错误建议。
从 MLOps 开始上手
由于模型运行在你的集群内部,因此由本地部署 InferenceService 支持的编码智能体非常适合用于平台本身的运维——你的 manifests、configs 和专有代码不会离开环境,这在受监管场景中尤其重要。适合的起始任务包括:
- 生成或修改
InferenceServiceYAML——例如:“为模型 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。