LMDeploy Anthropic 兼容接口实战:接入 Claude 风格客户端与网关

原创2026-09-26 19:22:112,448 阅读
文章标签:大模型模型推理服务推理引擎模型量化本地部署

LMDeploy Anthropic 兼容接口实战:接入 Claude 风格客户端与网关

导读

LMDeploy 在 OpenAI 兼容 API Server 之上提供了一套轻量级的 Anthropic 兼容接口,让 Anthropic 风格的客户端(如 Claude Code 类工具、Anthropic SDK 封装的网关)无需改造即可直连 LMDeploy 推理服务。本文以官方文档为骨架,结合仓库中 lmdeploy/serve/anthropic/ 的源码实现,完整讲解三个接口(/v1/messages、/v1/messages/count_tokens、/anthropic/v1/models)的调用方式、必要请求头、工具调用与推理输出(thinking block)、SSE 流式事件,以及请求校验与内部转换的底层原理,帮助读者在真实项目中正确启用并调试这套兼容层。

Anthropic 兼容接口的定位

LMDeploy 的核心服务能力由 lmdeploy/serve/openai/api_server.py 承载,Anthropic 兼容接口作为其中的一个独立路由模块挂载进来。从源码可以看到:

router = create_openai_router(server_context)
app.include_router(router)
app.include_router(create_anthropic_router(server_context))
app.include_router(create_responses_router(server_context))

也就是说,/v1/messages 等 Anthropic 风格端点与 OpenAI 风格端点共享同一套推理引擎(AsyncEngine)与解析器(parser)基础设施。路由组装逻辑集中在 lmdeploy/serve/anthropic/router.py:

def create_anthropic_router(server_context) -> APIRouter:
    router = APIRouter(tags=['anthropic'])
    merge_inline_system = not detect_inline_system_support(server_context.async_engine.chat_template)
    messages.register(router, server_context, merge_inline_system=merge_inline_system)
    messages_count_tokens.register(router, server_context, merge_inline_system=merge_inline_system)
    models.register(router, server_context)
    return router

其中 detect_inline_system_support 会通过一个哨兵字符串(__lmdeploy_inline_system_sentinel__)探测当前 chat template 是否支持把 system 消息内联渲染进 prompt(见 adapter.py);若不支持,则把请求中的 system 消息合并(merge)到对话开头,以保证 prompt 渲染正确。

支持的接口

接口 方法 说明
/v1/messages POST 对话补全,支持文本、推理(thinking)与工具调用(tool_use)输出
/v1/messages/count_tokens POST 基于 tokenizer 与 chat template 估算输入 token 数
/anthropic/v1/models GET 列出当前服务可用的模型名

三个端点的路由定义分别在 messages.py、messages_count_tokens.py 和 models.py 中。模型列表来自 server_context.async_engine.model_name 加上引擎配置中挂载的 LoRA 适配器名(get_model_list,见 adapter.py),返回体包含 id、display_name、created_at 等字段,并附带 has_more、first_id、last_id 分页信息。

必要请求头

对于 Anthropic 的 POST 接口,请求必须携带两个请求头:

  • content-type: application/json
  • anthropic-version: 2023-06-01(或其他可接受的版本字符串)

服务端校验实现位于 validation.py:

def _validate_headers(raw_request: Request):
    anthropic_version = raw_request.headers.get('anthropic-version')
    if not anthropic_version:
        return create_error_response(HTTPStatus.BAD_REQUEST, 'Missing required header: anthropic-version')
    return None

缺少 anthropic-version 会直接返回 400 Bad Request;count_tokens 端点同样强制该校验(见 messages_count_tokens.py)。GET /anthropic/v1/models 无需这些请求头。

示例:/v1/messages

最基础的对话补全请求如下:

curl http://{server_ip}:{server_port}/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": "Hello from Anthropic client"}]
  }'

字段说明(对应协议模型 protocol.py 中的 MessagesRequest):

  • model:必填,必须是当前服务已加载的模型名(或已挂载的 LoRA 适配器名),否则返回 404 not_found_error;
  • messages:Anthropic 格式的对话历史,role 支持 user、assistant、system,content 可以是字符串,也可以是 content block 列表(如 text、image、tool_use、tool_result、thinking 等);
  • max_tokens:必填,需大于 0,控制输出最大 token 数;
  • system:可选,系统提示词,可以是字符串或 block 列表;
  • stop_sequences:可选,自定义停止序列列表,会映射到 OpenAI 兼容层的 stop 参数;
  • stream:可选,布尔值,置为 true 时走 SSE 流式返回;
  • temperature、top_p、top_k:可选采样参数,其中 temperature 与 top_p 必须在 <a href="https://link.gitcode.com/i/0b1f8c30d97637cfdd97cdb7a44b33f5" target="_blank">0, 1] 内、top_k 不能为负数(校验逻辑见 [validation.py);
  • tools / tool_choice:可选,工具定义与工具选择策略,详见下文;
  • metadata、service_tier:可选,兼容字段。

除此之外,该端点还向后兼容了 LMDeploy generate 类接口的扩展字段:input_ids、image_data(多模态)、return_routed_experts、return_token_ids、return_logprob、include_stop_str_in_output。这些字段仅在 messages 为空时生效(input_ids 直接走原始 token 输入路径),且与 messages 互斥,混用会返回 400(见 validation.py)。

响应结构

非流式响应为 Anthropic Messages 风格,核心字段(MessagesResponse,见 protocol.py):

  • id:形如 msg_<uuid> 的消息 ID;
  • type: "message"、role: "assistant";
  • content:输出 block 列表,可能包含 text、thinking、tool_use 三种类型;
  • stop_reason:end_turn、max_tokens、stop_sequence、tool_use、parse_error 之一;
  • usage:input_tokens 与 output_tokens。

停止原因由 LMDeploy 内部的 finish reason 映射而来(adapter.py):

mapping = {
    'stop': 'end_turn',
    'length': 'max_tokens',
    'tool_calls': 'tool_use',
    'parse_error': 'parse_error',
    'abort': 'stop_sequence',
    'error': 'stop_sequence',
}

当启用 return_token_ids / return_logprob / return_routed_experts 时,响应还会附带 output_ids、output_token_logprobs((logprob, token_id) 元组列表)、routed_experts 等扩展字段。

示例:带 tools 的 /v1/messages

工具调用需要启动 API Server 时配置工具解析器(--tool-call-parser ...),否则请求会被拒绝(详见下文校验规则)。带工具的请求示例:

curl http://{server_ip}:{server_port}/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"}
  }'

要点说明:

  • 每个工具由 name、description、input_schema(JSON Schema)组成(ToolParam,见 protocol.py);
  • tool_choice 支持三种形式(protocol.py):
    • {"type": "auto"}:由模型自行决定是否调用工具;
    • {"type": "any"}:强制模型至少调用一个工具(要求至少提供一个工具);
    • {"type": "tool", "name": "search"}:强制调用指定名称的工具(该工具必须存在于 tools 中,否则 400);
  • 内部实现会把 Anthropic 工具定义转换为 OpenAI 兼容层的 Tool(to_openai_tools),并把 tool_choice 归一化为 OpenAI 语义(normalize_tool_choice,见 adapter.py):any → required,具名工具 → ToolChoice(function=...),其余 → auto。

工具调用前置条件

validation.py 中的校验规则明确要求:

  • 只要请求携带 tools,服务端就必须已配置工具解析器(parser_cls.tool_parser_cls 非空),否则返回 400:Please launch the api_server with --tool-call-parser if you want to use tool calling.;
  • {"type": "any"} 与 {"type": "tool"} 都要求请求中至少有一个工具。

启动示例(以指定模型与工具解析器启动 API Server):

lmdeploy serve api_server {model_path} \
  --server-port 23333 \
  --tool-call-parser anthropic

工具解析器与 OpenAI 兼容 chat 接口共用同一套 parser 栈(包括推理内容 block 的提取),因此启用方式与 OpenAI 工具调用一致,具体参数可参考 api_server.md 中的 --tool-call-parser 相关章节。模型推理产生工具调用后,输出会组装为 tool_use block:id、name、input(参数对象,来自解析器输出的 arguments JSON,见 adapter.py)。

推理输出(thinking block)

POST /v1/messages 支持把模型的推理内容(reasoning content)以 thinking block 输出。其提取依赖解析器配置——与 OpenAI 兼容 chat 接口使用同一套解析器。响应中的 thinking block 结构(protocol.py):

{
  "type": "thinking",
  "thinking": "模型推理内容...",
  "signature": "lmdeploy-local"
}

其中 signature 使用本地常量 LOCAL_THINKING_SIGNATURE = 'lmdeploy-local'(见 protocol.py)。同时,请求侧的 thinking / redacted_thinking block 也会在转换阶段被解析并写入 OpenAI 兼容消息的 reasoning_content 字段(见 adapter.py),从而支持多轮推理对话的上下文回传。

流式事件(SSE)

当 stream=true 时,/v1/messages 返回 text/event-stream 事件流。完整事件类型定义在 protocol.py,包括:

  • message_start:携带完整的 message 元信息(id、model、usage 等);
  • content_block_start:开启一个新的内容 block,携带 index 与初始 content_block;
  • content_block_delta:增量事件,其 delta 类型包括:
    • text_delta(文本增量,字段 text)
    • thinking_delta(推理增量,字段 thinking)
    • input_json_delta(工具参数 JSON 增量,字段 partial_json)
    • signature_delta(thinking 签名增量,字段 signature)
  • content_block_stop:结束当前内容 block;
  • message_delta:携带最终的 stop_reason、累计 usage.output_tokens 以及可选的 routed_experts;
  • message_stop:整个消息结束;
  • ping / error:心跳与错误事件。

事件序列化格式为标准的 SSE 协议,由 streaming.py 中的 _format_sse 实现:

def _format_sse(data: AnthropicStreamEvent) -> str:
    payload = data.model_dump(mode='json')
    for key in _OPTIONAL_EXTENSION_FIELDS:  # output_ids / output_token_logprobs / routed_experts
        if payload.get(key) is None:
            payload.pop(key, None)
    return f'event: {data.type}\ndata: {json.dumps(payload, ensure_ascii=False)}\n\n'

流式组装逻辑会按 text / thinking / tool_use 三类 block 维护块状态(_StreamBlockState,见 streaming.py),在 thinking block 结束时自动补发 signature_delta,与 content_block_start → content_block_delta → content_block_stop 的完整生命周期保持一致。扩展字段(如 output_ids、output_token_logprobs)仅在启用对应返回开关时随增量事件下发,否则被剔除。

示例:/v1/messages/count_tokens

用于在调用 messages 之前估算输入 token 数:

curl http://{server_ip}:{server_port}/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"}]
  }'

实现要点(messages_count_tokens.py):

  • 请求体字段包括 model、messages(至少一条,否则 400)、可选的 system 与 tools(CountTokensRequest,见 protocol.py);
  • model 不在已加载模型列表中时返回 404 not_found_error;
  • 统计逻辑基于 tokenizer 与 chat template(adapter.py):
def count_input_tokens(async_engine, messages: list[dict[str, str]]) -> int:
    prompt = async_engine.chat_template.messages2prompt(messages)
    token_ids = async_engine.tokenizer.encode(prompt, add_bos=True)
    return len(token_ids)

即先把消息按 chat template 渲染成完整 prompt,再用 tokenizer 编码得到 token 数。响应为 {"input_tokens": N}(CountTokensResponse)。需要说明的是:该接口不经过真正的模型前向,属于实用性估算,数值可能与实际推理时的输入长度存在细微差异。

请求转换与协议适配原理

Anthropic 与 OpenAI 的消息结构存在差异(例如 Anthropic 使用 content block、system 独立字段、tool_result/tool_use 回放等),兼容层通过 adapter.py 完成双向转换:

  • 入站转换:to_openai_messages 把 Anthropic 消息转换为 OpenAI 兼容消息——text block 映射为文本内容,image block 映射为 image_url(支持 url 与 base64 两种 source,见 _convert_image_source_to_url),tool_use block 映射为 tool_calls,tool_result block 映射为 tool 角色消息(支持携带图片结果),thinking block 写入 reasoning_content。当 chat template 不支持内联 system 时,_merge_system_messages 会把散落的 system 消息合并并前置;
  • 出站转换:build_message_content_blocks 把解析器产出的 text、tool_calls、reasoning_content 组装为 text / thinking / tool_use block 列表,其中工具参数由 arguments JSON 安全解析(解析失败时回退为 raw_arguments 字段);
  • 容错设计:ContentBlockParam 采用 extra='allow' 的宽松模型(protocol.py),以兼容 Claude Code 等客户端回放的包含 tool_use / tool_result 的 beta 历史会话;x-anthropic-billing-header 前缀的系统提示在转换时被过滤(见 _convert_system_message)。

这套转换在 messages.py 的端点实现中被统一调用:先 to_openai_messages 生成 OpenAI 风格消息,再构造 ChatCompletionRequest 交给 ChatRunner 执行推理,最后把结果重新组装为 Anthropic 响应结构(messages.py)。因此 Anthropic 兼容接口天然继承了 LMDeploy 引擎的推理、采样、工具解析与多模态能力。

常见错误与排查

现象 原因与处理
400: Missing required header: anthropic-version 请求缺少 anthropic-version 请求头,补上 -H "anthropic-version: 2023-06-01" 即可
404: The model 'xxx' does not exist 请求中的 model 与已加载模型名不一致,用 GET /anthropic/v1/models 确认可用的模型名
400: Please launch the api_server with --tool-call-parser 携带 tools 但服务未启用工具解析器,需以 --tool-call-parser ... 启动 API Server
400: temperature must be in [0, 1] / top_p 越界 / top_k 为负 采样参数超出合法范围,调整参数
400: input_ids cannot be used when messages is non-empty 扩展字段 input_ids/image_data 与 messages 混用,二者互斥
使用了 tool_choice 但未带 tools any / tool 类型都要求至少一个工具定义
工具结果未正确回传 确认多轮对话中 tool_result block 与 tool_use_id 书写正确,且 tool_use_id 与模型输出的 tool_use.id 对应

小结

LMDeploy 的 Anthropic 兼容接口以 lmdeploy/serve/anthropic/ 模块实现,通过协议转换层与 OpenAI 兼容服务共享同一推理引擎,支持文本、thinking 推理与 tool_use 工具调用三种输出,并提供 SSE 流式事件与基于 tokenizer 的 token 计数。接入 Anthropic 风格客户端只需满足 content-type: application/json 与 anthropic-version 两个请求头,工具调用需在服务端启用 --tool-call-parser。对于以 Claude 生态工具为入口的部署场景,这套兼容层提供了低成本迁移方案;相关实现可继续在 anthropic 目录、protocol.py 与 adapter.py 中深入阅读。

登录后查看全文
lmdeploy