LLM 网关 · LightAIP · frontend-intro-v5

1. 页面概览

LLM 网关页（路由 /admin/llm-gateway）是 AIP 管理后台面向管理员的大模型网关控制台，把平台 LLM 网关的运行态与配置态集中在一页：Provider 状态只读总览（可用性/模型/成本/熔断/健康）、LLM 路由规则与预算限额管理（成本管控）、Provider 持久化配置更新（API Key 加密写入）、用量统计面板（summary 指标 + 最近调用记录）以及网关试调。所有请求走 aipClient（/aip-api/v1 → AIP 18080）。

一句话总结：本页是 LLM 网关的「状态台 + 配置台 + 试调台」，管理员在此查看 Provider 健康、调整路由与预算、维护密钥并实时验证调用。

2. 访问入口

路由与菜单：path /admin/llm-gateway、name AdminLlmGateway、路由 title「LLM 网关」，位于 AIP 管理后台侧边栏（菜单项「LLM 网关」）；源码 action/web/src/views/LlmGatewayPage.vue。
认证与权限：父路由 /admin 配置 requiresAuth + requiresAdmin，需登录且 aip_is_admin === '1'；请求经 aipClient 附带 aip_token，401 清 token 跳 /login。
端口与 API 前缀：AIP 后端 18080，前端 baseURL /aip-api/v1（Vite 将 /aip-api 重写为 /api）。

3. 界面布局

+--------------------------------------------------------------+
| LLM 网关                                  [刷新]               |
| Provider 状态：名称|类型|可用|模型|成本(每1k)|熔断|健康           |
| LLM 路由规则（成本管控）：预算开关/用户限额/应用限额 [刷新路由]     |
|   表格：ID|任务类型|模型别名|候选Provider|降级链|限额(分)|启用|编辑 |
| Provider 配置更新（API Key 加密写入）：ID*/名称/服务地址/默认模型/ |
|   每千token成本/权重/API Key/优先级/说明+启用开关                |
|    [保存 Provider] [清空]                                     |
| 用量概览：指标卡 + 最近调用记录表                                |
| 网关试调：任务类型+消息 [发送试调][清空结果] → 结果+usage          |
+--------------------------------------------------------------+

各板块职责：

Provider 状态：只读展示各 Provider 运行态，空数据显示「暂无 Provider 数据（后端可能未就绪）。」。
LLM 路由规则（成本管控）：预算信息条 + 路由规则表格，行内「编辑」弹窗改预算/启用/候选/降级链。
Provider 配置更新：按 llm_providers 表主键 ID 更新持久化配置，api_key 加密写入，响应不回传密文。
用量概览：summary 指标卡（总调用次数/总 Tokens/平均延迟/成功率/总成本/降级次数）+ 最近调用记录表。

4. 交互元素

控件	位置	含义与作用
刷新	页面头部	并行刷新 providers / routes / usage，加载中禁用
编辑	路由表格操作列	打开「编辑路由 #ID」弹窗：预算限额（分，0=不限）、启用开关、候选 Provider（provider_order）、降级链（fallback_order）、说明；保存 `PUT /llm/routes/:id` 并热同步
保存 Provider	Provider 表单	校验 Provider ID 后 `PUT /llm/providers/:id`，成功后刷新状态表
清空	Provider 表单	重置表单为初始空值
发送试调	网关试调卡片	`POST /llm/chat`，结果展示 Provider/模型/延迟/成本/降级 + 返回内容 + usage

次要控件：预算 chip、试调「清空结果」、alert「关闭」、is_active 开关；任务类型下拉为 chat/nlq/generate_sql/summarize/esg_report/deep_report。

5. 后端关联

5.1 端点表

方法	路径	用途
GET	/llm/providers	Provider 运行态（name/kind/available/model/cost_per_1k/circuit_state/health），登录组
GET	/llm/usage?limit=100	用量 summary + 最近 records，登录组
POST	/llm/chat	网关试调，登录组
GET	/llm/routes	路由列表 + 预算（enabled/user_limit_cents/app_limit_cents），admin 组
PUT	/llm/routes/:id	部分更新路由，保存后热同步，admin 组
PUT	/llm/providers/:id	更新 Provider 配置，api_key 加密存储，admin 组

5.2 关键机制

DB 优先同步与热同步：网关启动/种子默认路由后调 SyncFromDB 从 llm_routes/llm_providers 表同步路由与 Provider；管理端点落库后再同步网关内存。
密钥加密存储：api_key 明文经前端提交，后端用 SECRET_KEY 派生的 AES-256-GCM 主密钥加密落库，响应不回传密文；API Key 留空表示不修改。
成本管控口径：cost_limit_cents 为单次调用预算（0=不限）；路由 enabled=false 时该任务走默认链；预算分用户级与应用级。
错误码：如 LLM_INVALID_REQUEST（400）、LLM_ROUTE_NOT_FOUND（404）、LLM_ROUTE_MGMT_UNAVAILABLE（503）；前端统一取 error/message 展示。

6. 权限与安全

页面挂在 /admin 管理组（requiresAdmin），非管理员被前端守卫拦到智能查询页。
Provider 列表/用量/chat 属 protected 登录组（普通用户可测）；路由与 Provider 写接口仅 admin 组可调。
API Key 不回显、AES-256-GCM 加密存储；AIP 内部 LLM 消费默认经 PIIGuard 脱敏，/llm/chat 直接转发端点不脱敏。

7. 常见问题与排错

现象：提示「加载 Provider 列表失败：...」。原因：后端未启动、Token 失效或 Vite 代理未指向 18080。处理：确认 AIP 服务存活、重新登录、检查 /aip-api 代理。
现象：路由表显示「暂无路由规则（后端可能未就绪，或未初始化路由表）」。原因：后端 repo 未配置或 llm_routes 未种子。处理：查看后端日志 SeedDefaultRoutes 是否成功，必要时重启后端种子。
现象：试调或用量报 401 跳登录页。原因：aip_token 过期，拦截器自动清 token。处理：重新登录后重试。
现象：保存 Provider 报 503「路由管理未配置」。原因：网关 repo/db 未注入。处理：检查后端配置，非页面可解决。

8. 已知缺陷与边界

项	说明
Provider 状态只读	状态表为运行时只读，修改需走下方「Provider 配置更新」表单
路由不可增删	页面仅支持编辑路由，新建/删除未在 UI 暴露
密钥不回显	编辑 Provider 时 API Key 留空表示不修改，无法查看已有密钥
用量口径依赖后端	summary 指标按后端 recorder 口径聚合，历史窗口与保留策略由后端决定