LMDeploy 接入 Claude Code 实战指南:用 `/v1/messages` 端点搭建 Anthropic 兼容网关

原创2026-09-25 18:18:181,348 阅读
文章标签:大模型模型推理服务推理引擎模型量化本地部署

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。

登录后查看全文
lmdeploy