SDK 接入

灵渠平台在数据平面提供一组协议兼容的统一查询入口：客户应用无需改写既有调用代码，只要把所用 SDK 的基址（base_url）指向灵渠，再把鉴权头换成灵渠下发的 API 密钥，即可让原本直连某一家模型供应方的请求转而经灵渠治理与转发。本节讲清接入原理、统一接入模式与额外参数透传，并指引到各 SDK 子页。

1. 接入原理：协议适配

灵渠在数据平面内建一组协议适配层，负责在客户 SDK 所用的供应方协议格式与灵渠内部统一处理管道之间做三件事：请求转换、响应规整、错误映射。换言之，客户继续用熟悉的 SDK 形态发请求，灵渠在入口处把它转换为内部统一形态送入中间件管道，再把上游返回结果按 SDK 期望的协议形态规整后返回。

由此，客户在保留既有 SDK 架构不变的前提下，自动获得灵渠的全部治理能力——智能路由、缓存检查点、安全护栏、多上游聚合、统一计量计费。结构转换、字段对齐、错误码归一这些适配开销由平台承担，客户侧只需一次基址切换。

能力边界。 协议适配层只做格式转换与字段对齐，不改写生成内容；请求进入管道后的治理与上游选择，遵循 中间件管道 描述的统一编排。客户看到的响应结构与直连供应方保持兼容，灵渠在 usage 中额外扩展计价词元计量字段（cached_input_tokens / price_tier / thinking），且 model 字段返回实际路由命中的上游中性名（各 SDK 子页「计量字段」段有完整示例）。

2. 统一接入模式

灵渠的统一查询入口对齐 OpenAI 协议事实标准，同时兼容 Anthropic 等主流形态。客户可按既有技术栈选择对应 SDK，全部指向同一个数据平面入口：

一次最小接入只需三步，三步都在客户侧完成、无需联系平台：

1. 改基址：把 SDK 的 base_url 指向 <平台入口地址>/v1。
2. 换密钥：把鉴权头中的供应方密钥换成在控制台创建的灵渠 API 密钥。
3. 用中性名：把请求里的模型名换成灵渠统一中性名（可经数据平面 GET /v1/models 拉取当前可用清单）。

# 接入前（直连某家供应方）
client = SomeProviderSDK(api_key="<供应方密钥>")

# 接入后（指向灵渠，OpenAI 兼容形态）
client = SomeProviderSDK(
    base_url="<平台入口地址>/v1",
    api_key="tsxt-************************"  # 灵渠 API 密钥
)

模型一律以统一中性名出现；上游的批发价等成本口径仅在运营控制台可见，不随数据平面返回给客户应用。路由由平台按请求复杂度自动研判并择优转发，客户不必在请求中指定具体上游。

3. 额外参数透传

当客户需要使用某些尚未被统一入口直接识别的上游特有请求参数时，无需另起端点——仍走同一个统一查询入口 <平台入口地址>/v1/chat/completions，只要在请求头加 x-lq-passthrough-extra-params: true，请求体中平台未识别的顶层字段就会被原样合并进发往上游的请求。请求仍完整流经灵渠的中间件管道，因而逐条计量、用量明细、安全护栏等治理能力照常生效。

# 同一统一入口，加 x-lq-passthrough-extra-params 头即可透传上游特有参数
curl <平台入口地址>/v1/chat/completions \
  -H "Authorization: Bearer tsxt-************************" \
  -H "x-lq-passthrough-extra-params: true" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<上游模型中性名>",
    "messages": [ { "role": "user", "content": "携带上游特有参数的请求" } ],
    "custom_param": "value"
  }'

上游鉴权一律由灵渠的密钥配置注入，不从客户请求转发；客户请求只需携带灵渠 API 密钥。额外参数透传只对 JSON 请求生效，平台已处理的标准参数不会重复透传。该开关与其余逐请求选项的完整约束见 请求选项透传与覆写 · 额外参数透传。

4. 渐进式迁移建议

已有规模化调用的客户，建议分阶段把流量切到灵渠，降低一次性切换风险：

# 用配置开关在直连与灵渠之间切换，便于灰度与回退
import os

def resolve_base_url() -> str:
    if os.getenv("USE_LINGQU", "false") == "true":
        return "<平台入口地址>/v1"      # 经灵渠
    return "<供应方官方端点>"            # 直连（回退路径）

每条业务线建议单独申请一把灵渠 API 密钥（按部门 / 业务线 / 成本中心建子账户），用量逐请求归属到对应子账户分账；密钥与额度管理见 快速开始 · 创建 API 密钥。

子页导航

相关链接

• 快速开始：从部署到首个请求跑通的最短链路，含创建密钥与控制台核对。
• 中间件管道：接入后请求在平台内的治理流转——路由、缓存检查点、安全护栏。
• API 参考：数据平面统一查询入口与控制平面管理接口的端点契约。