将编码智能体与本地部署的推理服务结合使用
目录
简介前提条件各部分如何协同工作步骤 1:部署并对端点进行冒烟测试步骤 2:在运行时启用 tool 调用步骤 2b(可选):配置 reasoning 模型和 reasoning effort服务端参数配置 reasoning effort 和思考行为服务端默认值请求级控制步骤 3:连接你的编码智能体opencodeCodex CLIClaude Code选项 1:LiteLLM 代理选项 2:claude-code-router本地部署运行说明最佳实践推荐用于编码智能体的模型家族选择适合你硬件的模型HuggingFace 上来自 Unsloth 的量化模型硬件适配指南调优推理服务性能从 vibe coding 开始从 MLOps 开始故障排查参考资料简介
opencode、Codex CLI 和 Claude Code 等编码智能体是基于终端的助手,它们会读取你的仓库、规划变更、编辑文件,并代表你执行命令。它们通常通过互联网与托管模型提供商通信。
本文档演示如何将这些智能体指向你在 Alauda AI 上自托管的模型,从而使源代码、提示词和基础设施配置永远不会离开你的集群。你为其他工作负载部署的同一个本地部署 InferenceService 也可以为交互式编码智能体提供支持,前提是它暴露了一个 OpenAI-compatible API 且启用了 tool(function)调用。opencode 和 Codex CLI 可以直接调用该端点;Claude Code 使用 Anthropic Messages API(/v1/messages),并且需要一个轻量级翻译代理(请参见 Claude Code)。
本页面直接基于部署操作指南展开,不再重复如何创建或暴露 InferenceService;而是链接到相关内容,并聚焦于智能体特定的配置和调优。
编码智能体及其配置格式演进很快。下面的配置片段是基于撰写本文时可用版本的正确起点。请始终以你所使用智能体的最新上游文档为准,确认字段名称。
前提条件
- 一个正在运行且就绪的
InferenceService,提供 OpenAI-compatible API。请参见 使用 CLI 创建推理服务。 - 运行智能体的机器能够访问服务端点的网络。如果需要从集群外部的开发者笔记本访问,请参见 为推理服务配置外部访问。
- 一个支持 tool/function calling 的模型,并启用了匹配的 vLLM parser(请参见 在运行时启用 tool 调用)。如果没有这个能力,智能体可以聊天,但不能编辑文件或运行命令。
- 本地已安装智能体 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 不提供该接口。它需要在 OpenAI-compatible 端点前面放置一个小型翻译代理(请参见 Claude Code)。
步骤 1:部署并对端点进行冒烟测试
按照 使用 CLI 创建推理服务 将模型部署为 InferenceService,如果智能体运行在集群外部,则按照 为推理服务配置外部访问 进行暴露。
在接入任何智能体之前,先确认端点可以响应 chat 请求。如果基础 URL、模型名称或认证信息错误,编码智能体往往会以令人困惑的方式失败,因此请先用 curl 做验证:
正常的 JSON completion 表明端点可达且模型名称正确。请记录下你会在所有智能体配置中复用的三个值:base URL(以 /v1 结尾)、模型名称(--served-model-name)以及 API key。
对于 reasoning 模型(DeepSeek R1、QwQ、Qwen3 等),还需要在 vLLM 启动参数中添加匹配的 --reasoning-parser。请参见 配置 reasoning 模型和 reasoning effort。
步骤 2:在运行时启用 tool 调用
编码智能体通过调用工具(读取文件、写入文件、运行 shell)来工作。这要求模型既要输出 tool calls,又要让 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 calls;如果模型卡要求,请传入
--chat-template。 - 如果你提供的是 reasoning 模型,还要启用匹配的
--reasoning-parser,以便智能体接收到干净的 assistant content,并与 reasoning traces 分离。
通过让智能体执行一个简单的文件操作来验证端到端 tool 调用(例如:“创建一个包含 hi 这个单词的 hello.txt 文件”)。如果模型返回的是自然语言而不是编辑文件,则说明 tool calling 没有正确接入——请重新检查 parser 和模型配置。
步骤 2b(可选):配置 reasoning 模型和 reasoning effort
某些模型(例如 DeepSeek R1、QwQ、Hunyuan 或 Cohere Command A Reasoning)会在最终答案之前输出 chain-of-thought reasoning。vLLM 会将 reasoning traces 与 assistant content 分离,从而让智能体获得干净的输出——但你必须启用匹配的参数。
服务端参数
将 --reasoning-parser 添加到你的 vLLM 启动命令中。如果同一个模型还需要智能体 tool 调用,则将其与相应的 --tool-call-parser 配对使用:
下表展示了常见模型家族及其所需的 parser。请结合 vLLM tool calling 文档 确认当前列表。
对于上表未列出的模型家族,请查看模型卡中的 reasoning 说明,以及 vLLM tool calling 文档,以确认匹配的 parser 对。
配置 reasoning effort 和思考行为
Reasoning effort 控制模型在回答之前“思考”多少。对于编码智能体,通常希望使用 低 reasoning effort,以保持交互延迟可接受——多次短小、低推理的轮次,通常优于一次长时间、高推理的轮次。
服务端默认值
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 特定的请求字段:
对于支持显式思考预算的 parser,你也可以为每个请求限制 reasoning token 数:
如果使用翻译代理(LiteLLM 或 claude-code-router),在依赖这些字段之前,请确认代理版本会透传这些 vLLM/OpenAI 扩展字段。
只有在确认你的具体 vLLM 镜像和模型 template 接受 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:
- 模型 key(
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_*标志才是真正让“on-prem”部署保持本地化的关键:如果没有它们,Claude Code 仍可能向 Anthropic 托管端点发出非必要请求,并向模型请求本地部署模型无法满足的功能(1M 上下文、超大输出等)。claude-code-router 会自动设置其中部分标志。ANTHROPIC_MODEL必须与InferenceService暴露的模型名称一致(即--served-model-name)。- 可选地,将
ANTHROPIC_SMALL_FAST_MODEL设置为本地部署模型,这样后台/低成本请求也能保持本地化。
Claude Code 的智能体能力在很大程度上取决于所提供模型的 tool-calling 可靠性——优先选择指令跟随和工具调用能力都较强的模型,并在依赖之前确认 tool calls 能够端到端正常回传。
最佳实践
推荐用于编码智能体的模型家族
Qwen3.6 和 Gemma 4 是我们目前推荐用于本地部署编码智能体的两个模型家族。它们都具有较强的指令微调能力,并提供多种尺寸和量化格式;请结合你运行的 vLLM 版本确认其 tool-calling parser 支持情况。
选择适合你硬件的模型
先从你已有的 GPU 内存出发,再选择在 KV cache 方面仍留有余量的最大可用模型。粗略的权重大小估算公式为 parameters × bytes-per-parameter——FP16 约为 2 字节,FP8/INT8 约为 1 字节,INT4 约为 0.5 字节——此外 KV cache 和运行时开销还会消耗更多内存。请至少保留 15–25% 的余量。
HuggingFace 上来自 Unsloth 的量化模型
Unsloth 发布了最新模型的 GGUF 量化版本,并针对 vLLM 的快速加载进行了优化。下表列出了对编码智能体最实用的几款:
**注意:**GGUF 量化模型可通过
--quantization gguf在 vLLM 中加载。对于 AWQ 或 GPTQ INT4 变体,请查看 huggingface.co/models——搜索qwen3.6 AWQ或gemma-4 GPTQ可找到社区量化版本。Unsloth 的 QAT(quantization-aware training)模型通常在激进比特宽度下仍能保持比事后量化更高的质量。
硬件适配指南
其他选型建议:
- 优先选择面向代码、并经过指令微调的模型,且要原生支持 tool/function calling。如果模型卡没有提到 tool calling,智能体将无法可靠地编辑文件。
- 在确定使用前,确认该模型存在匹配的 vLLM parser(请参见 在运行时启用 tool 调用)。Qwen3-Coder 模型使用
qwen3_xml;请在你的 vLLM 版本文档中确认 Qwen3.6 和 Gemma 4 的 parser 支持。 - **为上下文长度留出预算。**编码智能体会发送很大的提示词(系统提示词 + 文件和仓库上下文)。请选择上下文窗口能够覆盖你最大预期提示词的模型,并记住更长的
--max-model-len会为每个请求消耗更多 KV cache 内存,从而降低并发。 - **量化在本地部署中是乘法器。**INT4(AWQ/GPTQ)或 GGUF 量化可以让你在相同 VRAM 中运行明显更强的模型,这通常比原始 FP16 精度更影响智能体质量。
- **MoE 模型尤其高效。**Qwen3.6-35B-A3B 和 Gemma 4-26B-A4B 每个 token 仅激活 3–4B 个参数,却拥有更大的知识库,在仅付出一小部分 VRAM 成本的情况下,能获得接近 dense model 的质量。
调优推理服务性能
编码智能体流量有其独特形态:长且高度重复的提示词(同一系统提示词和仓库上下文会在每一轮重复发送)、短交互请求的突发流量,以及对首 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 模式,启动更快但运行更慢)。服务稳定后,切换到 non-eager 以捕获 CUDA graphs,但代价是启动时间更长。 - 通过
--max-num-seqs和--max-num-batched-tokens调整 batching,以在你的并发级别下平衡吞吐和单请求延迟。 - 在内存紧张时使用 FP8 KV cache(
--kv-cache-dtype fp8),以延长上下文长度并提高并发。 - 当模型无法放入单卡时,使用
--tensor-parallel-size将大模型切分到多张 GPU 上。 - 考虑 speculative decoding,以降低智能体循环中的交互延迟——请参见 vLLM 推理服务的 Speculative Decoding。
- **注意自动扩缩容和冷启动。**对于单用户交互式智能体使用场景,请保持
minReplicas: 1——从 0 扩到 1 会增加数分钟的冷启动,在任务进行中会非常影响体验。对于突发性的多开发者使用场景,请有意识地配置自动扩缩容;请参见 为推理服务配置扩缩容 和 使用 KEDA 为推理服务设置自动扩缩容。 - **允许长请求。**智能体轮次可能运行时间较长;请相应地设置 Knative 的
serving.knative.dev/progress-deadline注解和客户端超时。如果请求被中断,请参见 推理超时故障排查。
从 vibe coding 开始
“vibe coding”——通过描述意图并让智能体编写代码来快速迭代——在基本配置正确后,配合自托管模型非常有效:
- 从一个能舒适运行在你的 GPU 上、且仍留有余量的 Qwen3.6 或 Gemma 4 模型开始;一个响应更快的小模型,通常比一个迟缓的大模型更适合交互式流程。对于 24 GB GPU,
Qwen3.6-35B-A3B(MoE)是极好的起点。 - 为代码生成设置 低温度(大约
0–0.2),以保持编辑结果可预测并减少乱跑。 - 在尝试任何实际任务之前,先用一个简单任务验证 tool 调用(例如“创建一个文件并运行它”)。
- 保持提示词聚焦——只打开或引用相关文件,让智能体上下文保持在主题上,同时降低 prefill 成本。
- 以小步、可审查的方式工作,并在接受每个 diff 前先阅读。频繁提交,以便可以干净地回滚错误建议。
从 MLOps 开始
由于模型运行在你的集群内部,使用本地部署 InferenceService 作为后端的编码智能体,非常适合用于操作平台本身——你的 manifests、配置和专有代码都不会离开环境,这在受监管环境中特别重要。适合作为起点的任务包括:
- 生成或修改
InferenceServiceYAML——例如,“为目标是 24 GB GPU 的模型 X 编写一个InferenceService,启用 prefix caching 和 tool calling。” - 添加自动扩缩容、调度或资源配置——例如 KEDA/KPA 自动扩缩容、感知 CUDA 版本的调度,或 Kueue/Volcano 队列管理。
- 为你的模型生命周期编写并调整流水线和监控。
- 形成闭环:使用智能体部署一个模型,然后继续使用同一个本地部署模型驱动后续的平台操作。
关于更详细的 MLOps 工作流——管理 InferenceService、配置网关、迭代调优性能以及规划微调任务——请参见 使用编码智能体和本地部署 LLM 运行 MLOps。
故障排查
- **智能体会聊天,但从不编辑文件或运行命令。**未启用 tool calling,或者 parser 与模型不匹配——请参见 在运行时启用 tool 调用。
- **
model not found/ 404。**智能体配置中的模型名称与--served-model-name不匹配,或者 base URL 没有以/v1结尾。 - **401 / 403。**智能体发送的 API key 错误,或没有发送 API key,而端点或网关需要它。
- **长任务请求超时。**增加 Knative 的
progress-deadline注解和客户端超时——请参见 推理超时故障排查。 - **空闲后的首次请求非常慢。**服务已缩容到 0 并正在冷启动;对于交互式使用,请设置
minReplicas: 1。