数据平面
灵渠平台数据平面 /v1/* 的端点契约——OpenAI 兼容统一查询入口、模型列表与统一计价词元计数，含请求与响应 JSON 示例
数据平面是平台的推理接入面，前缀 /v1，OpenAI 兼容。客户应用以一套兼容主流大模型协议的接口接入，把基址指向平台入口、鉴权头换成平台密钥即可复用既有 SDK。每一次查询请求进入平台后，先依次经过路由、缓存检查点、安全护栏三层中间件治理（见 中间件管道与扩展点 SDK），再转发至最合适的上游模型。
数据平面只暴露统一入口，内部的分流与治理细节不对客户应用暴露。本面共三个端点：
| 方法 | 路径 | 用途 |
|---|---|---|
POST | /v1/chat/completions | 统一查询入口；发起一次推理请求 |
GET | /v1/models | 列出可调用的模型清单 |
POST | /v1/token-count | 统一计价词元计数（可核验计数） |
认证统一为 Authorization: Bearer <API 密钥>，逐请求鉴权并归属到对应子账户分账。
1. 统一查询入口
POST /v1/chat/completionsOpenAI 兼容的统一查询入口。请求经三层中间件治理后路由至上游模型，响应在标准 OpenAI 结构之上，于 usage 中携带六档计价词元用量信息。
关键参数
| 参数 | 含义 |
|---|---|
model | 目标模型中性名；平台据此与复杂度研判结果共同决定实际路由的上游 |
messages | 对话消息数组（role + content），OpenAI 标准形态 |
stream | 是否流式返回；流式下每个数据块逐 chunk 经护栏处理 |
max_tokens | 最大输出词元数 |
temperature 等 | 其余 OpenAI 标准采样参数，透传至上游 |
请求示例
curl https://your-platform/v1/chat/completions \
-H "Authorization: Bearer tsxt-************************" \
-H "Content-Type: application/json" \
-d '{
"model": "<上游模型中性名>",
"messages": [
{ "role": "system", "content": "<系统提示>" },
{ "role": "user", "content": "<用户查询>" }
],
"stream": false,
"max_tokens": 1024
}'响应示例（OpenAI 兼容 chat.completion，usage 含六档计量；下示数值仅为占位）
{
"id": "<响应标识>",
"object": "chat.completion",
"created": 0,
"model": "<实际路由的上游模型中性名>",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "<生成内容>" },
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 0,
"completion_tokens": 0,
"total_tokens": 0,
"cached_input_tokens": 0,
"price_tier": "<适用单价档（六档之一）>",
"thinking": false
}
}usage 的扩展字段承载计量信息：cached_input_tokens 为命中上游缓存的输入词元数，price_tier 标明本次落入的计量档（输入命中 / 未命中 × thinking / no-thinking + 输出，共六档），thinking 标明是否走深度推理档。这些字段是逐条调用记录与后续计费、对账的请求侧来源。
流式形态。
stream: true时，响应以多个chat.completion.chunk逐块返回；每个 chunk 都会经安全护栏中间件逐块处理，计量在流末汇总为一条完整的逐条调用记录。护栏拦截命中时，返回结构化的拒答结果而非正常生成内容。
2. 模型列表
GET /v1/models列出当前 API 密钥可调用的模型清单。返回内容已按该子账户的授权模型范围过滤，模型一律以统一中性名呈现。
请求示例
curl https://your-platform/v1/models \
-H "Authorization: Bearer tsxt-************************"响应示例（OpenAI 兼容 list 结构）
{
"object": "list",
"data": [
{ "id": "<模型中性名>", "object": "model", "owned_by": "lingqu" }
]
}中性名口径。 数据平面返回的模型一律为统一中性名，不暴露上游来源与批发口径；上游接入配置、成本口径等仅在运营控制台「模型接入」页可见。某个子账户能调用哪些模型，由其在控制台配置的模型范围决定。
3. 统一计价词元计数
POST /v1/token-count统一计价词元计数接口，对给定文本 / 消息按平台统一计价词元口径计数。该接口为确定性计数——对相同输入返回相同结果，便于客户在发请求前预估词元数与适用档位，也便于事后对逐条调用记录中的词元数复算核对计费。
关键参数
| 参数 | 含义 |
|---|---|
model | 目标模型中性名（不同模型的计数口径可能不同） |
messages 或 text | 待计数的消息数组或纯文本 |
thinking | 是否按 thinking 档计数（影响适用单价档判定） |
请求示例
curl https://your-platform/v1/token-count \
-H "Authorization: Bearer tsxt-************************" \
-H "Content-Type: application/json" \
-d '{
"model": "<上游模型中性名>",
"messages": [
{ "role": "user", "content": "<待计数文本>" }
],
"thinking": false
}'响应示例（按六档计量分列；数值仅为占位）
{
"input_tokens": 0,
"output_tokens_estimate": 0,
"cache_hit": false,
"thinking": false,
"price_tier": "<适用单价档（六档之一）>",
"metering_version": "<当期统一计价词元计量口径版本号>"
}| 字段 | 含义 |
|---|---|
input_tokens | 输入词元数（确定性，可对相应文本复算核对） |
output_tokens_estimate | 输出词元数预估 |
cache_hit | 是否命中上游缓存（以上游返回为准） |
thinking | 是否 thinking 档 |
price_tier | 适用单价档（六档之一） |
metering_version | 当期统一计价词元计量口径版本号，随响应返回，便于核对计量口径版本 |
可核验计数。 本接口与逐条调用记录共用同一套计量口径：逐条调用记录中的
input_tokens/output_tokens可经本接口对相应文本复算核对，确保计量可验证。计量口径版本号随响应返回，口径升级时版本号随之变化。逐条调用记录的查询见 控制平面 · 用量与计量明细。
下一步
- 控制平面：控制台管理接口的分组端点契约，含用量明细、账单、密钥、额度、对账等。
- 中间件管道与扩展点 SDK：数据平面每次请求所经的路由 / 缓存检查点 / 安全护栏三层治理。
- 多上游模型接入：
/v1/models背后的上游聚合接入与模型池准入门槛。