LMDeploy 接入 Claude Code 实战指南:用 `/v1/messages` 端点搭建 Anthropic 兼容网关
LMDeploy 接入 Claude Code 实战指南:用 /v1/messages 端点搭建 Anthropic 兼容网关
本文以 LMDeploy 的 Anthropic 兼容接口为核心,讲解如何将本地或远程部署的 LMDeploy api_server 接入 Claude Code:只需设置 ANTHROPIC_BASE_URL,Claude Code 即可把请求路由到 LMDeploy 的 POST /v1/messages 端点,实现本地模型驱动的编码助手。读完本文,你将掌握服务端启动、端点连通性验证、Claude Code 环境变量配置、流式(SSE)行为以及模型发现机制,并能对照源码理解请求转换与响应组装的全过程。
整体请求链路
Claude Code 是 Anthropic 生态的终端编码代理,它通过设置 ANTHROPIC_BASE_URL 即可连接任何 Anthropic 兼容网关。LMDeploy 暴露了 Anthropic 兼容的 POST /v1/messages 端点,因此 Claude Code 可以把请求路由到本地或远程的 LMDeploy api_server。完整链路如下:
Claude Code -> http://<server>:<port>/v1/messages -> LMDeploy api_server
从源码看,这一兼容层位于 lmdeploy/serve/anthropic,由 router.py 中的 create_anthropic_router 统一组装三个端点:
POST /v1/messages:核心对话生成端点;POST /v1/messages/count_tokens:按 tokenizer/聊天模板估算输入 token 数;GET /anthropic/v1/models:Anthropic 风格的模型列表。
此外,LMDeploy 官方文档 Anthropic-Compatible Endpoints 对这三个端点的请求头、示例与流式事件做了系统说明,可作为配置时的权威参考。
1. 启动 LMDeploy API 服务
首先用 Claude Code 打算使用的模型启动一个 LMDeploy API server。以 Qwen/Qwen3.5-35B-A3B 为例:
lmdeploy serve api_server Qwen/Qwen3.5-35B-A3B --backend pytorch --server-port 23333
参数说明:
Qwen/Qwen3.5-35B-A3B:模型路径或 Hugging Face 模型 ID,位置参数model_path可以是本地目录,也可以是模型仓库中的模型 ID(见 lmdeploy/cli/serve.py);--backend pytorch:指定推理后端为 PyTorch 引擎;--server-port 23333:服务监听端口。源码中该参数默认值为None,未设置时生效默认值23333(见 lmdeploy/cli/serve.py),因此这里显式指定与默认行为一致,便于记忆;--server-name:监听地址,默认0.0.0.0,远程访问时按需修改。
如果需要工具调用(tool calling),必须按模型支持的解析器启动服务,通过 --tool-call-parser 指定解析器名称:
lmdeploy serve api_server <model> \
--server-port 23333 \
--tool-call-parser <parser-name>
这一点在源码中也有印证:api_server 的 CLI 解析器会注册 tool_call_parser 参数(lmdeploy/cli/serve.py),并在构造服务时透传给 vllm_meta 层(lmdeploy/cli/serve.py)。官方端点文档同样明确指出:工具调用要求以配置了 --tool-call-parser ... 的方式启动 API server,且 reasoning 块的抽取同样依赖该解析器栈(与 OpenAI 兼容的 chat 端点共用同一套解析器,见 docs/en/llm/api_server_anthropic.md)。不同模型对应的解析器名称可参考仓库中的 tool_parser 目录 与 autotest 中针对 Anthropic 风格的解析器测试,例如 autotest/interface/restful/tool_parser/test_tool_call_anthropic_sdk.py。
2. 验证 Messages 端点
在配置 Claude Code 之前,先用 curl 确认 LMDeploy 能正确响应 Anthropic 风格的请求:
curl http://127.0.0.1:23333/v1/messages \
-H "content-type: application/json" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "Qwen/Qwen3.5-35B-A3B",
"max_tokens": 128,
"messages": [
{"role": "user", "content": "Say hello from LMDeploy"}
]
}'
两个关键点:
model字段必须与 LMDeploy 服务暴露的模型名完全一致。服务端在 adapter.py 的get_model_list中返回async_engine.model_name及所有 adapters,模型名不匹配会直接报错;- 必须携带
anthropic-version请求头。POST端点依赖此头做校验(count_tokens端点甚至在_validate_headers中强制要求该头,缺失返回 400,见 messages_count_tokens.py)。
带工具定义的请求示例
若服务以工具解析器启动,可在请求体中携带 tools 与 tool_choice:
curl http://127.0.0.1:23333/v1/messages \
-H "content-type: application/json" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "intern-s2-preview",
"max_tokens": 128,
"messages": [{"role": "user", "content": "Find lmdeploy docs"}],
"tools": [{
"name": "search",
"description": "Search docs",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string"}
},
"required": ["query"]
}
}],
"tool_choice": {"type": "auto"}
}'
在请求转换层,Anthropic 的 tools 会被映射为 OpenAI 协议的函数工具(adapter.py),tool_choice 则按规则归一化:None/auto → auto、any → required、tool 指定名称 → 对应的 OpenAI ToolChoice(adapter.py)。
token 估算端点
Claude Code 等客户端常会先估算 token,可用 count_tokens 端点验证:
curl http://127.0.0.1:23333/v1/messages/count_tokens \
-H "content-type: application/json" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "intern-s2-preview",
"system": "You are a helpful assistant.",
"messages": [{"role": "user", "content": "Count these tokens"}]
}'
该端点基于 tokenizer 与聊天模板做实际估算(adapter.py 中通过 chat_template.messages2prompt 拼 prompt 后 tokenizer.encode 统计长度),属于实用估算而非与 Anthropic 官方完全一致的精确计数。
3. 配置 Claude Code
将 ANTHROPIC_BASE_URL 设置为 server 根路径,而不是 /v1——Claude Code 会自行拼接 /v1/messages。把 LMDeploy 网关配置写入 ~/.claude/settings.json:
{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:23333",
"ANTHROPIC_AUTH_TOKEN": "dummy",
"ANTHROPIC_MODEL": "Qwen/Qwen3.5-35B-A3B",
"ANTHROPIC_CUSTOM_MODEL_OPTION": "Qwen/Qwen3.5-35B-A3B",
"ANTHROPIC_CUSTOM_MODEL_OPTION_NAME": "LMDeploy local model",
"ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION": "Served by LMDeploy /v1/messages",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "Qwen/Qwen3.5-35B-A3B",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "Qwen/Qwen3.5-35B-A3B",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "Qwen/Qwen3.5-35B-A3B",
"CLAUDE_CODE_SUBAGENT_MODEL": "Qwen/Qwen3.5-35B-A3B",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
}
}
各变量的作用:
| 环境变量 | 说明 |
|---|---|
ANTHROPIC_BASE_URL |
网关根地址(不含 /v1),Claude Code 自行追加 /v1/messages |
ANTHROPIC_AUTH_TOKEN |
认证令牌,自建网关可填任意占位值如 dummy |
ANTHROPIC_MODEL |
指定使用的模型名 |
ANTHROPIC_CUSTOM_MODEL_OPTION |
在模型选择列表中注册自定义模型的 ID |
ANTHROPIC_CUSTOM_MODEL_OPTION_NAME |
自定义模型的展示名称 |
ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION |
自定义模型的展示描述 |
ANTHROPIC_DEFAULT_SONNET/OPUS/HAIKU_MODEL |
分别覆盖 Claude Code 对 Sonnet/Opus/Haiku 三类默认模型的选择,全部指向本地模型 |
CLAUDE_CODE_SUBAGENT_MODEL |
子代理(subagent)使用的模型 |
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC |
设为 1 关闭非必要遥测流量 |
模型名必须与 LMDeploy 暴露的模型名完全一致(大小写、命名空间均需匹配,服务端由 get_model_list 决定哪些名字合法)。
随后启动 Claude Code:
claude --model Qwen/Qwen3.5-35B-A3B
4. 流式行为(Streaming)
Claude Code 默认大量使用流式响应。LMDeploy 的 /v1/messages 端点支持 stream=true,并返回 Anthropic 风格的 server-sent events(SSE)。服务端在 streaming.py 中把推理生成流逐块转换为标准事件序列,典型事件流为:
message_start
content_block_start
content_block_delta
content_block_stop
message_delta
message_stop
其中 content_block_delta 依据内容类型携带不同 delta:
text_delta:普通文本增量;thinking_delta:推理(reasoning)增量——仅当解析器配置启用了推理块抽取时才会出现;input_json_delta:工具输入 JSON 的增量——仅在启用工具调用时出现;signature_delta:推理块结束时补发的本地签名,源码中签名字符串为lmdeploy-local(见 protocol.py)。
实现细节可从源码中得到印证:
- usage 前置:
message_start事件必须在内容为空时携带 usage 信息,因此 streaming.py 会先缓冲一个已解析的 chunk 来填充input_tokens,再让该 chunk 走正常的内容块路径; - 块状态管理:
_StreamBlockState负责text/thinking/tool_use三类内容块的开启、切换与关闭,保证事件索引连续(streaming.py); - 终止原因映射:
map_finish_reason将引擎的 finish reason 转换为 Anthropic 的stop_reason——stop→end_turn、length→max_tokens、tool_calls→tool_use、parse_error→parse_error、abort/error→stop_sequence(adapter.py)。
非流式响应的内容块同样由 adapter.py 的 build_message_content_blocks 组装:按顺序产出 thinking 块(推理内容)、text 块(正文)、tool_use 块(工具调用,含解析后的 JSON 入参)。
5. 模型发现说明(Model Discovery)
当 ANTHROPIC_BASE_URL 指向网关时,Claude Code 可能会查询 /v1/models 来发现可用模型。LMDeploy 的 Anthropic 模型列表端点目前文档化的路径为 GET /anthropic/v1/models(路由定义见 endpoints/models.py,返回结构为 Anthropic 风格的 data/has_more/first_id/last_id)。
如果 Claude Code 没有自动发现你的模型,请按第 3 节所示显式设置 ANTHROPIC_MODEL 与 ANTHROPIC_CUSTOM_MODEL_OPTION,通过环境变量直接指定模型名,这是最稳妥的兜底方案。
常见排查要点
- 404 / 模型不存在:确认请求中的
model与 LMDeploy 暴露的模型名逐字符一致;count_tokens端点对不存在的模型返回not_found_error(messages_count_tokens.py); - 400 校验失败:检查是否携带
content-type: application/json与anthropic-version头;max_tokens必须大于 0(protocol.py 中Field(gt=0)约束); - 工具不生效:确认服务是以
--tool-call-parser启动的,且解析器与模型匹配; - 流式事件缺失:检查客户端是否发送了
"stream": true,以及是否按text/event-stream解析 SSE; - 多模态与回退输入:
/v1/messages协议模型还预留了input_ids与image_data回退字段——当messages为空时可用原始 token 序列和图片数据直接输入(protocol.py),适合与/generate风格调用对接的进阶场景。
如需深入了解这三个端点的完整请求/响应结构与更多示例,可直接查阅 Anthropic-Compatible Endpoints 官方文档;底层协议模型定义见 lmdeploy/serve/anthropic/protocol.py,请求转换逻辑见 lmdeploy/serve/anthropic/adapter.py,流式事件组装见 lmdeploy/serve/anthropic/streaming.py。