将编码智能体与本地部署的推理服务结合使用
目录
简介前提条件各组件如何协同工作步骤 1:部署并对端点执行冒烟测试步骤 2:在运行时启用工具调用步骤 2b(可选):配置推理模型和推理工作量服务端标志配置推理工作量和思考行为服务端默认值请求时控制第 3 步:连接你的编码智能体opencodeCodex CLIClaude Code选项 1:LiteLLM 代理选项 2:claude-code-router本地部署注意事项最佳实践面向编码智能体的推荐模型选择适配硬件的模型适配硬件的量化变体硬件适配指南调优推理服务性能启用 MTP(多令牌预测)开始使用 vibe coding开始使用 MLOps故障排除参考资料简介
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;相反,本文会链接到相关内容,并重点介绍智能体专用的配置和调优。
编码智能体及其配置格式变化很快。以下配置片段是根据撰写本文时可用的版本提供的正确起点。请始终根据所使用智能体的当前上游文档确认字段名称。
前提条件
- 一个正在运行且已就绪的
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,因此可以直接调用
InferenceService端点。 - Claude Code 使用 Anthropic Messages API,而 vLLM 不提供该 API。它需要在 OpenAI-compatible endpoint 前面配置一个小型转换代理(请参阅 Claude Code)。
步骤 1:部署并对端点执行冒烟测试
按照使用 CLI 创建推理服务将模型部署为 InferenceService;如果智能体在集群外运行,请按照为推理服务配置外部访问公开端点。
在连接任何智能体之前,请确认端点可以响应聊天请求。如果基础 URL、模型名称或身份验证配置错误,编码智能体可能会以令人困惑的方式失败,因此请先使用 curl 进行验证:
正常的 JSON completion 表明端点可访问且模型名称正确。请记下每个智能体都会重复使用的三个值:基础 URL(以 /v1 结尾)、模型名称(即 --served-model-name)和 API key。
对于支持推理的模型(推荐集合中的 GLM-5.2 和 Qwen3.6,以及支持推理模式的 Deepseek-v4 构建版本),还应将匹配的 --reasoning-parser 添加到 vLLM 启动标志中。请参阅配置推理模型和推理工作量。
步骤 2:在运行时启用工具调用
编码智能体通过调用工具来工作(读取文件、写入文件、运行 shell)。这要求模型生成工具调用,并且 vLLM 对其进行解析。在 InferenceService 的 vLLM 启动命令中添加以下标志(在使用 CLI 创建推理服务的示例中,应将其添加到 python3 -m vllm.entrypoints.openai.api_server 行):
- 解析器必须与模型匹配。例如,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 配对:
下表列出了用于参考的解析器组合。解析器名称与版本相关,并且会随着 vLLM 版本的发布而变化——请始终根据您运行版本的 vLLM 工具调用文档进行确认。
这些模型系列的确切 --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 来启用或禁用思考:
使用 OpenAI Python 客户端时,请通过 extra_body 传递 vLLM 专属的请求字段:
对于支持显式思考预算的解析器,还可以限制每个请求的推理令牌数:
使用转换代理(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 兼容提供程序:
- 模型键(
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 密钥的环境变量: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 端点:
这会公开 http://localhost:4000/v1/messages(Anthropic 格式),并将请求转发到你的 OpenAI 兼容后端。
然后将 Claude Code 指向该代理:
选项 2:claude-code-router
在 ~/.claude-code-router/config.json 创建配置文件,并将你的 InferenceService 设为提供程序:
然后通过路由器启动 Claude 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 构建(请参阅适配硬件的量化变体)。
请根据所运行的 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(量化感知训练)构建在激进位宽下比事后量化更能保持模型质量。对于推荐模型,最实用的构建如下:
注意: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 引擎上提供服务。推荐的两个模型已经提供经过验证和基准测试的配置方案:
如需在 NPU 上量化自有权重,请使用 ModelSlim workbench 镜像及其验证 notebook(请参阅创建 Workbench)。
硬件适配指南
其他选择建议:
- 限定在五个推荐模型系列内。 它们都经过指令调优,并原生支持工具/函数调用 — 这是智能体可靠编辑文件的前提。如果转而使用模型卡未提及工具调用的模型,通常意味着智能体只能聊天而无法执行操作。
- 在确定模型之前,确认存在匹配的 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 字符串和令牌数量因模型和版本而异;以下是经过验证的配置方案中的值:
请根据 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 支持和标志名称可能会变化。
MTP 加速的是解码而不是预填充,其收益取决于流量中的预测接受率。在确定启用之前,请在具有代表性的编码智能体工作负载上分别进行启用和禁用 MTP 的基准测试,并测量实际的每令牌延迟(ITL):MTP 步骤会在每个流式块中输出多个令牌,因此块级延迟会低估每令牌收益。在上述 Ascend 配置中,W8A8/W4A8 量化为更大的 KV cache 释放了 HBM,但不会直接加快 MTP 解码路径。
开始使用 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),以保持编辑结果的确定性并减少无效尝试。 - 在尝试实际任务之前,先使用一个简单任务(“创建文件并运行它”)验证工具调用。
- 保持提示聚焦 — 仅打开或引用相关文件,使智能体上下文保持主题一致,并降低预填充成本。
- 分解为较小且易于审查的步骤,并在接受每次修改前阅读 diff。经常提交,以便干净地回滚错误建议。
开始使用 MLOps
由于模型在集群内部运行,由本地部署的 InferenceService 支持的编码智能体非常适合用于运维平台本身 — 你的 manifests、配置和专有代码不会离开环境,这对于受监管场景十分重要。适合开始的任务包括:
- 生成或修改
InferenceServiceYAML — 例如,“为模型 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。
参考资料
- 使用 Coding Agents 和本地部署 LLM 运行 MLOps
- 使用 CLI 创建 Inference Service
- 配置 Inference Services 的外部访问
- 配置 Inference Services 的扩缩容
- 使用 KEDA 为 Inference Services 设置自动扩缩容
- vLLM Inference Services 的推测解码
- 扩展 Inference Runtimes
- 工具调用 — vLLM
- 推理输出 — vLLM
- 自动前缀缓存 — vLLM
- opencode 文档
- Codex CLI
- Claude Code 文档
- LiteLLM
- claude-code-router