LMDeploy Anthropic 兼容接口实战:接入 Claude 风格客户端与网关
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/jsonanthropic-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 兼容消息——textblock 映射为文本内容,imageblock 映射为image_url(支持 url 与 base64 两种 source,见_convert_image_source_to_url),tool_useblock 映射为tool_calls,tool_resultblock 映射为tool角色消息(支持携带图片结果),thinkingblock 写入reasoning_content。当 chat template 不支持内联 system 时,_merge_system_messages会把散落的 system 消息合并并前置; - 出站转换:
build_message_content_blocks把解析器产出的text、tool_calls、reasoning_content组装为text/thinking/tool_useblock 列表,其中工具参数由 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 中深入阅读。