概述
灵渠平台是什么、单系统双控制台形态，以及每一次查询请求依次经路由、缓存检查点、安全护栏中间件治理的核心理念
灵渠（LingQu）是一套面向企业的可编程 AI 网关平台。它把多家上游模型供应方的能力统一为一个查询入口，并以一条可编排的中间件管道对每一次查询请求逐一治理：路由、缓存检查点、安全护栏三类中间件按既定顺序依次执行，研判请求复杂度、择优转发至最合适的上游模型，并以统一计价词元口径完成计量、计费与额度风控。
平台对所经的每一次请求独立担责、自主定价、统一结算；同时聚合自有供应模型与第三方兼容模型，并自营路由小模型的微调能力。本文档面向部署、运维与集成灵渠平台的内部管理员，先用一页讲清"平台是什么、长什么样、怎么治理每一次请求"，再指引到其余各节。
平台能力一览
| 能力 | 说明 |
|---|---|
| 统一查询入口 | 一套兼容主流大模型协议的接口，客户应用以此发起推理请求，无需感知背后的多上游聚合 |
| 智能路由 | 按请求复杂度自动研判，择优转发至最合适的上游模型，支持重试与故障转移 |
| 缓存检查点 | 命中上游模型供应商缓存时短路返回，不重复消耗上游推理 |
| 安全护栏 | 注入防护、敏感信息脱敏、应拒答拦截、访问控制等治理处置 |
| 统一计量计费 | 以统一计价词元口径逐条计量，按子账户分账、按结算月出具服务费用结算单 |
| 多上游聚合 | 自有供应模型（含自托管）与第三方兼容接入并存，统一管理路由优先级与权重 |
| 路由小模型微调 | 在部署实例内训练路由小模型，按正反样本持续优化路由决策 |
| 信用额度风控 | 单层汇总信用额度约束全部子账户密钥，达额预警与暂停 |
| 双部署模式 | 私有化部署于客户控制环境，或 SaaS 部署于供应方环境（VM 级逻辑隔离） |
单系统、双控制台
灵渠以单一系统形态交付，但向两类读者呈现两套控制台。两套控制台共享同一套数据底座——同一批查询、同一组模型、同一份用量，仅菜单分组与呈现口径随读者切换。
| 控制台 | 读者 | 主要职责 |
|---|---|---|
| 客户 Portal | 接入服务的企业客户 | 查询服务状态、用量明细、账单结算、安全防护统计、模型评测与服务质量、API 密钥与额度管理 |
| 运营控制台 | 平台运营/网关管理人员 | 中间件管道编排、多上游模型聚合接入、路由小模型微调、部署与许可、数据安全，以及供应商对账与上游服务质量监控 |
同源原则。 客户 Portal 看到的用量、账单与额度数字，与运营控制台的对应明细出自同一份底座，逐条之和等于分项之和等于汇总，跨页面核对时数字始终对得上。运营控制台另含供应商对账、年度承诺用量进度等内部运营口径，不在客户 Portal 呈现。
核心治理理念：每一次请求都被治理
灵渠的本体是一条有序中间件管道。每一个查询请求进入平台后，不会被直接转发给上游模型，而是依次经过三类中间件的治理，最终带着完整的计量与处置结果返回。
查询请求
│
▼
① 路由中间件 研判复杂度 → 选定上游模型 → 加权择优、健康检查、必要时重试/故障转移
│
▼
② 缓存检查点中间件 命中上游缓存则短路返回，不再调用上游；未命中则继续
│
▼
③ 安全护栏中间件 注入防护 / 脱敏 / 应拒答拦截 / 访问控制；流式响应逐 chunk 处理
│
▼
转发至选定的上游模型 → 计量计费 → 返回（含 6 档计价词元用量）三类中间件的编排顺序、条件分支与短路行为，都在运营控制台的中间件编排页可视化呈现并可调整位次。每个中间件节点支持前置（Pre）与后置（Post）两个对称扩展点：前置 Hook 按注册顺序正序执行，后置 Hook 逆序执行，保证状态收敛与清理对称。即使在某一节点短路（如缓存命中），已执行的前置 Hook 也都会得到对应的后置 Hook。
能力边界。 中间件只在控制面/治理面对请求施加处置——路由、缓存判定、护栏拦截与脱敏——并不对结果内容做实质性的生成或加工。生成由所选定的上游模型完成，平台对治理过程负责，对生成内容不做改写。
平台对外暴露两类接口平面，分别承载"发起一次查询"与"看数据、管配置"：
| 平面 | 前缀 | 用途 | 认证方式 |
|---|---|---|---|
| 数据平面 | /v1/* | 兼容主流大模型协议的统一查询入口，客户应用以此发起推理请求 | Authorization: Bearer <API key> |
| 控制平面 | /api/v1/* | 控制台的查询、统计、配置、对账等全部管理功能 | 控制台登录会话 |
一次最简单的查询调用示意如下（数据平面，OpenAI 兼容形态）：
curl https://<平台入口地址>/v1/chat/completions \
-H "Authorization: Bearer <API key>" \
-H "Content-Type: application/json" \
-d '{
"model": "<上游模型中性名>",
"messages": [
{ "role": "user", "content": "请帮我归纳这段会议纪要的要点" }
],
"stream": false
}'响应在标准 OpenAI 兼容结构之上，于 usage 中携带本次请求的计价词元用量信息：
{
"object": "chat.completion",
"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": "<适用单价档（6 档之一）>",
"thinking": false
}
}计量口径速读。 平台按"输入·缓存命中 / 输入·缓存未命中 / 输出"三类计量项，各自再分 thinking 与 no-thinking 档，合计 6 档统一计价词元口径。缓存命中档的计价更低，thinking（深度推理）档相对溢价；上游缓存是否命中以上游返回为准。具体单价、信用额度、承诺值等商务数值不在文档中固化，以服务协议与控制台实时口径为准。