Anthropic SDK 接入

以 Anthropic 官方 SDK（Python / JavaScript）改 base_url 接入灵渠——Messages 形态配置、流式、计量字段、自定义头、能力对照与注意事项

灵渠的数据平面除对齐 OpenAI 协议事实标准外，同时兼容 Anthropic 的 Messages 形态。已使用 Anthropic 官方 SDK 的客户应用，只需把客户端的 base_url 指向灵渠、把密钥换成灵渠 API 密钥，即可在不改写 Messages 调用代码的前提下接入灵渠，同样获得智能路由、缓存检查点、安全护栏、多上游聚合与统一计量计费等能力。

统一入口前缀： /v1/*（数据平面，Messages 形态为 /v1/messages）。下文示例中的 <平台入口地址> 请替换为你的平台实例统一入口地址。

1. 接入配置

把 Anthropic 官方 SDK 的 base_url 指向 <平台入口地址>，鉴权改用灵渠 API 密钥即可。Messages 调用代码保持不变。

import anthropic

# 把客户端指向灵渠
client = anthropic.Anthropic(
    base_url="<平台入口地址>",
    api_key="tsxt-************************"  # 灵渠 API 密钥
)

# Messages 调用照旧
response = client.messages.create(
    model="<上游模型中性名>",
    max_tokens=1000,
    messages=[{"role": "user", "content": "你好，帮我列出这份合同的关键条款。"}]
)

print(response.content[0].text)

import Anthropic from "@anthropic-ai/sdk";

// 把客户端指向灵渠
const anthropic = new Anthropic({
  baseURL: "<平台入口地址>",
  apiKey: "tsxt-************************", // 灵渠 API 密钥
});

// Messages 调用照旧
const response = await anthropic.messages.create({
  model: "<上游模型中性名>",
  max_tokens: 1000,
  messages: [{ role: "user", content: "你好，帮我列出这份合同的关键条款。" }],
});

console.log(response.content[0].text);

改动仅此一处：基址指向灵渠、密钥换成灵渠下发的子账户密钥。Anthropic SDK 形态下 max_tokens 等参数照常透传；模型名填灵渠统一中性名，由平台按复杂度自动研判并择优转发到最合适的上游。

2. 流式响应

Anthropic SDK 的流式形态同样兼容，逐事件返回：

with client.messages.stream(
    model="<上游模型中性名>",
    max_tokens=1000,
    messages=[{"role": "user", "content": "分三点说明这个改动的影响。"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

const stream = await anthropic.messages.stream({
  model: "<上游模型中性名>",
  max_tokens: 1000,
  messages: [{ role: "user", content: "分三点说明这个改动的影响。" }],
});
for await (const event of stream) {
  if (event.type === "content_block_delta") {
    process.stdout.write(event.delta.text ?? "");
  }
}

流式请求下，灵渠的安全护栏对每个数据块逐块施加出站处置，治理结论在生成过程中即时生效；计量在流末汇总，整条流落一条逐条调用记录（详见中间件管道 · 流式逐 chunk 处理）。

3. 计量字段

灵渠在 Anthropic Messages 兼容响应结构之上，于 usage 中携带本次请求的计价词元计量信息：

{
  "type": "message",
  "role": "assistant",
  "model": "<实际路由的上游模型中性名>",
  "content": [{ "type": "text", "text": "..." }],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 26,
    "output_tokens": 41,
    "cached_input_tokens": 0,
    "price_tier": "input-miss-no-thinking",
    "thinking": false
  }
}

字段	含义
`input_tokens` / `output_tokens`	输入 / 输出词元数（统一计价词元口径）
`cached_input_tokens`	命中上游缓存的输入词元数
`price_tier`	本次落入的计量档（六档之一）
`thinking`	本次是否走 thinking（深度推理）档

计量口径与 OpenAI 形态一致：以统一计价词元为唯一口径，按"输入·命中 / 输入·未命中 / 输出"三类各分 thinking 与 no-thinking 档，合计六档。发请求前可调用 POST /v1/token-count 预估词元数与适用档位。

4. 自定义请求头

Anthropic 官方 SDK 支持在客户端构造时声明默认头，用于透传客户侧追踪标识：

client = anthropic.Anthropic(
    base_url="<平台入口地址>",
    api_key="tsxt-************************",
    default_headers={
        "x-lq-trace-id": "<客户侧自定义追踪标识>"
    }
)

const anthropic = new Anthropic({
  baseURL: "<平台入口地址>",
  apiKey: "tsxt-************************",
  defaultHeaders: {
    "x-lq-trace-id": "<客户侧自定义追踪标识>",
  },
});

子账户归属由 API 密钥本身决定。自定义追踪标识仅用于把客户侧日志与灵渠逐条调用记录关联对账，不影响路由与计量结论。

5. 能力对照

Anthropic SDK 接入支持 Anthropic SDK 与灵渠核心功能交集内的全部能力——即只要 Anthropic SDK 支持、灵渠核心也支持的特性，接入后即可无缝使用。

能力	接入后表现
Messages（含多轮、系统提示）	完整支持，形态与直连一致
流式响应（`messages.stream`）	完整支持，护栏逐块治理
`max_tokens` 等生成参数	照常透传至选定上游
计量字段（`usage`）	在标准结构上扩展六档计价词元字段
thinking（深度推理）档	复杂请求路由至更强上游时按 thinking 档计量
缓存检查点	命中上游缓存时短路返回，对应档计量单价更低

6. 注意事项

基址形态：Anthropic 官方 SDK 会在 base_url 之后拼接 /v1/messages，请确保最终请求落在 <平台入口地址>/v1/messages 上。
max_tokens 必填：Anthropic Messages 形态要求显式给出 max_tokens，接入灵渠后该约束不变。
密钥仅在创建时返回一次：灵渠 API 密钥在控制台创建时返回密钥本体一次，请妥善保存。
额度联动暂停：全部子账户共用一层汇总信用额度，达额时全部密钥一并暂停，请求返回对应错误。
模型名用中性名：请以灵渠统一中性名为准，可经 GET /v1/models 获取当前清单；勿填某家供应方私有模型名。