将编码智能体与本地部署的推理服务结合使用
目录
简介前提条件各组件如何协同工作步骤 1:部署并进行端点冒烟测试步骤 2:在运行时启用 tool calling步骤 2b(可选):配置 reasoning models 和 reasoning effort服务端参数配置 reasoning effort 和 thinking 行为服务端默认值请求时控制步骤 3:连接你的编码智能体opencodeCodex CLIClaude Code选项 1:LiteLLM 代理选项 2:claude-code-router本地部署运行注意事项最佳实践推荐用于编码智能体的模型选择适配你硬件的模型适配你硬件的量化版本硬件适配指南调优 inference service 性能启用 MTP(multi-token prediction)开始进行 vibe coding开始进行 MLOps故障排查参考资料简介
opencode(opencode)、Codex CLI 和 Claude Code 这类编码智能体是基于终端的助手,它们会读取你的仓库、规划变更、编辑文件,并代表你运行命令。它们通常通过互联网与托管的模型提供商通信。
本文档展示如何将这些智能体指向你在 Alauda AI 上自托管的模型,从而让你的源代码、提示词和基础设施配置永远不会离开集群。只要暴露的是 OpenAI-compatible API,并且启用了 tool(function)calling,你为其他工作负载部署的同一个本地部署 InferenceService 也可以为交互式编码智能体提供支持。opencode 和 Codex CLI 可以直接调用该端点;Claude Code 使用 Anthropic Messages API(/v1/messages),因此需要一个轻量级转换代理(参见 Claude Code)。
本页直接建立在部署操作指南之上。它不会重复如何创建或暴露 InferenceService;而是链接到相关内容,并重点介绍面向智能体的配置与调优。
编码智能体及其配置格式演进很快。下面的配置片段适用于撰写本文时可用的版本,作为起点是正确的。请始终以你所使用智能体的最新上游文档为准,确认字段名称。
前提条件
- 一个正在运行且就绪的
InferenceService,提供 OpenAI-compatible API。参见 使用 CLI 创建 Inference Service。 - 运行智能体的机器可访问该服务端点的网络。如果智能体运行在集群外的开发者笔记本上,请参见 为 Inference Services 配置外部访问。
- 一个支持 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 创建 Inference Service 部署你的模型为 InferenceService;如果智能体运行在集群外,则按照 为 Inference Services 配置外部访问 暴露该服务。
在接入任何智能体之前,先确认端点可以响应聊天请求。如果 base URL、模型名称或认证配置错误,编码智能体会以令人困惑的方式失败,因此请先用 curl 验证:
一个正常的 JSON completion 表明端点可达且模型名称正确。注意你后续为每个智能体都会复用的三个值:base URL(以 /v1 结尾)、model name(--served-model-name)以及 API key。
对于具备推理能力的模型(在推荐集合中,包括 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 那一行):
- 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.2 和 Qwen3.6(reasoning 默认开启),以及 reasoning-mode 的 Deepseek-v4 构建。vLLM 会把 reasoning traces 与 assistant content 分离,这样你的智能体就能收到干净的输出——但你必须启用匹配的参数。
服务端参数
将 --reasoning-parser 添加到你的 vLLM 启动命令中。如果同一个模型还需要 agent tool calls,则将其与合适的 --tool-call-parser 配对使用:
下表展示了 parser 配对供参考。parser 名称与版本相关,并且会随 vLLM 版本变化——请始终以你所运行版本的 vLLM tool calling 文档 为准。
这些家族对应的精确 --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:
使用 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一致。 - 导出配置中引用的密钥,然后选择该模型:
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 格式),并将请求转发到你的 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 选项一起使用)必须非空,但如果你的代理和端点不会检查它们,其内容并不重要;请在端点或代理层面进行访问控制(参见 管理网关,了解如何通过 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 构建(参见 适配你硬件的量化版本)。
请根据你运行的 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)构建在激进位宽下比后量化更能保持质量。以下是推荐模型中最有用的构建:
注意: 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 surface 在 vLLM-Ascend engine 上提供服务的 W8A8 / W4A8 权重。推荐模型中已有两个以经过验证、基准测试的 recipe 形式提供:
如果要在 NPU 上量化你自己的权重,请使用 ModelSlim workbench 镜像及其验证 notebook(参见 创建 Workbench)。
硬件适配指南
其他选择建议:
- 保持在这五个推荐家族之内。 这些模型都经过 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-A3B、GLM-5.2和Deepseek-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-MTP和Deepseek-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-MTP 和 Deepseek-v4——都带有原生 multi-token-prediction(MTP) head,可以在每个 decode 步骤中提议多个 token,从而降低智能体循环中的交互延迟,而无需额外管理 draft model。MTP 是一种 speculative decoding,可通过运行时的 speculative-decoding 配置启用。
vLLM。 将模型的 MTP method 传给 --speculative-config。method 字符串和 token 数量因模型和版本而异;以下是已验证 recipe 中使用的值:
请根据你的 vLLM 版本确认准确的 method,并将完整 recipe——包括这些在 Ascend 上需要的 MTP guardrails(关闭 prefix caching、限制 --max-num-seqs、enforce_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 支持和参数名会变化。
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”——通过描述意图并让智能体编写代码来快速迭代——在基础设置正确后,与自托管模型配合得很好:
- 从一个与你的 GPU 余量匹配的推荐模型开始——
Qwen3.6-35B-A3B或Gemma4-12B-it都是不错的首选;一个响应更快的小模型,通常比一个迟缓的大模型更适合交互式流程。对于 24 GB GPU,Qwen3.6-35B-A3B(MoE,约 3B active)是极佳的起点。 - 为代码生成设置一个 低 temperature(大约
0–0.2),以保持编辑确定性并减少反复试错。 - 在尝试任何实际任务之前,先用一个简单任务验证 tool calling(例如“创建一个文件并运行它”)。
- 保持提示词聚焦——只打开或引用相关文件,让智能体的上下文保持在主题上,同时降低 prefill 成本。
- 采用小而可审查的步骤工作,并在接受每个 diff 之前先阅读它。频繁提交,这样你就可以干净地回滚不合适的建议。
开始进行 MLOps
由于模型运行在你的集群内部,基于本地部署 InferenceService 的编码智能体非常适合用来运维平台本身——你的 manifests、配置和专有代码都不会离开环境,这在受监管场景中尤为重要。适合作为起点的任务包括:
- 生成或修改
InferenceServiceYAML——例如,“为模型 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。
参考资料
- 使用编码智能体和本地部署 LLM 运行 MLOps
- 使用 CLI 创建 Inference Service
- 为 Inference Services 配置外部访问
- 为 Inference Services 配置 Scaling
- 使用 KEDA 为 Inference Services 设置 Autoscaling
- vLLM Inference Services 的 Speculative Decoding
- 扩展 Inference Runtimes
- Tool Calling — vLLM
- Reasoning Outputs — vLLM
- Automatic Prefix Caching — vLLM
- opencode 文档
- Codex CLI
- Claude Code 文档
- LiteLLM
- claude-code-router