OpenAI SDK 接入

以 OpenAI 官方 SDK（Python / JavaScript）改 base_url 接入灵渠——配置示例、模型列表、流式、自定义头、能力对照与注意事项

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

统一入口前缀： /v1/*（数据平面）。下文示例中的 <平台入口地址> 请替换为你的平台实例统一入口地址（可在运营控制台「平台设置 · 接入参数」查看）。

1. 接入配置

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

import openai

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

# 业务调用照旧
response = client.chat.completions.create(
    model="<上游模型中性名>",
    messages=[{"role": "user", "content": "你好，帮我归纳这段会议纪要的要点。"}]
)

print(response.choices[0].message.content)

import OpenAI from "openai";

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

// 业务调用照旧
const response = await openai.chat.completions.create({
  model: "<上游模型中性名>",
  messages: [{ role: "user", content: "你好，帮我归纳这段会议纪要的要点。" }],
});

console.log(response.choices[0].message.content);

改动仅此一处：基址指向灵渠、密钥换成灵渠下发的子账户密钥。模型名填灵渠统一中性名——平台会按请求复杂度自动研判并择优转发到最合适的上游，客户无需指定具体上游。

2. 列出可用模型

数据平面提供 OpenAI 兼容的模型列表端点，返回当前在灵渠模型池内、对该密钥可用的统一中性名清单：

models = client.models.list()
for m in models.data:
    print(m.id)

curl <平台入口地址>/v1/models \
  -H "Authorization: Bearer tsxt-************************"

返回的模型一律为统一中性名。密钥创建时若设置了 model_scope（允许调用的模型范围），列表只返回该范围内的模型；留空则返回模型池内全部可用模型。上游的批发价等成本口径不随该端点返回给客户应用。

3. 流式响应

设置 stream: true 即可获得逐块（chunk）返回的流式响应，形态与直连 OpenAI 一致：

stream = client.chat.completions.create(
    model="<上游模型中性名>",
    messages=[{"role": "user", "content": "用三段话讲清这个方案的要点。"}],
    stream=True
)
for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)

流式请求下，灵渠的安全护栏对每个 chunk 逐块施加出站处置，确保治理结论在生成过程中即时生效，不让未经复核的内容先于护栏抵达客户端（详见中间件管道 · 流式逐 chunk 处理）。计量在流末汇总，整条流落一条逐条调用记录。

4. 计量字段

灵渠在标准 OpenAI 兼容响应结构之上，于 usage 中携带本次请求的计价词元计量信息，便于客户侧复算核对计费：

{
  "object": "chat.completion",
  "model": "<实际路由的上游模型中性名>",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 24,
    "total_tokens": 42,
    "cached_input_tokens": 0,
    "price_tier": "input-miss-no-thinking",
    "thinking": false
  }
}

字段	含义
`prompt_tokens` / `completion_tokens`	输入 / 输出词元数（统一计价词元口径）
`cached_input_tokens`	命中上游缓存的输入词元数
`price_tier`	本次落入的计量档（输入命中 / 未命中 × thinking / no-thinking + 输出，共六档）
`thinking`	本次是否走 thinking（深度推理）档

发请求前若需预估词元数与适用档位，可调用统一计价词元计数接口 POST /v1/token-count。具体单价、信用额度等商务数值以服务协议与控制台显示为准。

5. 自定义请求头

部分治理能力可经请求头透传，OpenAI 官方 SDK 支持在客户端构造时声明默认头：

client = openai.OpenAI(
    base_url="<平台入口地址>/v1",
    api_key="tsxt-************************",
    default_headers={
        "x-lq-trace-id": "<客户侧自定义追踪标识>"   # 便于把客户日志与灵渠逐条记录对账
    }
)

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

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

6. 能力对照

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

能力	接入后表现
Chat Completions（含多轮）	完整支持，形态与直连一致
流式响应（`stream: true`）	完整支持，护栏逐 chunk 治理
模型列表（`/v1/models`）	返回灵渠统一中性名清单
计量字段（`usage`）	在标准结构上扩展六档计价词元字段
多上游聚合	由灵渠按路由自动择优，客户无需感知具体上游
缓存检查点	命中上游缓存时短路返回，对应档计量单价更低

7. 注意事项

基址带 /v1：OpenAI 官方 SDK 默认会在 base_url 之后再拼接路径，请确保最终请求落在 <平台入口地址>/v1/chat/completions 上；若你的 SDK 版本对 base_url 末段处理不同，请相应调整。
密钥仅在创建时返回一次：灵渠 API 密钥在控制台创建时返回密钥本体一次，请妥善保存；丢失需重新创建。
额度联动暂停：全部子账户共用一层汇总信用额度，达额时全部密钥一并暂停，请求会返回 429。额度状态可在控制台密钥与额度管理页查看。
模型名用中性名：请勿在 model 字段填某家供应方的私有模型名；以灵渠统一中性名为准，可经 GET /v1/models 获取当前清单。