`desc` 是中文给运维看的,`params` 只对 vendor 有意义(passthrough 是空数组)。 `/api/v1/me` 把条目下发给用户 AI 后,AI 必须能自己拼出: - 路径尾部是什么(/ocr /ocr/base64 /ocr/url) - 每个端点的 Content-Type(multipart 还是 json) - 上游字段名 / Swagger 在哪 加 `usage_hint` 字段:管理员按 OpenAPI 风格填写自由格式,由 /api/v1/me 原样透传给用户 AI。AI 直接解析,无需再读人工文档。 设计要点: - 不进 shm(热路径只查 base/key/asset_id/mode,进 shm 占带宽) - 截断到 1KB(够写 3-5 个端点说明,长 Swagger 截断而非拒绝) - 默认空字符串,向后兼容旧数据 - passthrough 推荐填,vendor 可选填 改动: - models.rs: ApiProxy 加 usage_hint 字段 - apix.rs: upsert 收 usage_hint_raw + 截断;view 回显 - api.rs: save 解析 usage_hint;响应回显 - www/apix.html: 描述加 usage_hint 解释 - www/assets/apix.js: 表单加 textarea + 提交带 usage_hint - tests/llm/e2e.sh: §11.5 加 1 条 usage_hint 写入与回显断言 - 回归 227/0 全绿(修复断言 1 条)
101 lines
4.4 KiB
Rust
101 lines
4.4 KiB
Rust
//! API 代理持久化模型(`api-proxies.json`:以 slug 为 key)。
|
||
//!
|
||
//! 字段名与旧版 `data/api-proxies.json` **逐字对应**,以便新版直接接管旧数据文件。
|
||
|
||
use serde::{Deserialize, Serialize};
|
||
use std::collections::BTreeMap;
|
||
|
||
/// API 代理表(`api-proxies.json`)。
|
||
///
|
||
/// 与 `llm-upstreams.json` 同构:每条记录 = 一个供应商(自带基址与密钥),
|
||
/// 由 `slug` 区分。调用方访问 `/apix/<slug>?参数=值`,网关用本记录里的密钥
|
||
/// 转发到供应商、并把响应原样返回。不同供应商彼此独立、互不耦合。
|
||
///
|
||
/// `key` 是供应商真 Key,**敏感级别等同 `users.json`**(data/ 已 gitignore)。
|
||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||
pub struct ApiProxyStore {
|
||
/// slug → 代理映射
|
||
#[serde(default)]
|
||
pub items: BTreeMap<String, ApiProxy>,
|
||
}
|
||
|
||
impl Default for ApiProxyStore {
|
||
fn default() -> Self {
|
||
Self { items: BTreeMap::new() }
|
||
}
|
||
}
|
||
|
||
/// 单个 API 代理条目:指向某一家供应商的一个可调用的资产。
|
||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||
pub struct ApiProxy {
|
||
/// 供应商侧的资产 id(如 `searxng-search`),决定具体调用哪个资产。
|
||
/// **vendor 模式必填**;passthrough 模式用不到(上游路径由 URL 尾部决定),可留空。
|
||
pub asset_id: String,
|
||
/// 供应商名称(仅展示用,管理员自填,例如 `provider-x` / 客户自定)
|
||
#[serde(default)]
|
||
pub supplier: String,
|
||
/// 供应商基址,如 `https://api.example.com`
|
||
#[serde(default)]
|
||
pub base: String,
|
||
/// 供应商 API Key(`ak_...`)。留空 = 未配置,热路径直接 503。
|
||
/// **敏感**:写盘与回显都按密钥处理,管理台只回显掩码。
|
||
/// passthrough 模式下若上游不需要鉴权可留空(不下发任何鉴权头)。
|
||
#[serde(default)]
|
||
pub key: String,
|
||
/// 代理模式:
|
||
/// - `vendor`(默认):单一供应商收口 `POST {base}/api/v1/ai/request`,
|
||
/// 请求体由网关按 `asset_id` 拼装(见 `apix.rs`)。
|
||
/// - `passthrough`:透传模式,原样转发客户端的方法/请求体/Content-Type,
|
||
/// 上游路径 = `{base} + /apixp/<slug> 之后的 URI 尾部`,用于 OCR / 文生图 /
|
||
/// TTS 这类「多端点、多 body、无 asset 市场」的内部 REST 服务。
|
||
#[serde(default = "default_mode")]
|
||
pub mode: String,
|
||
/// 展示名(中文)
|
||
#[serde(default)]
|
||
pub name: String,
|
||
/// 一句话说明
|
||
#[serde(default)]
|
||
pub desc: String,
|
||
/// **声明式参数清单**(如 `["q"]`)。
|
||
///
|
||
/// 只用于给调用方看的文档(管理台把 `?q=关键词` 拼出来、账号态接口回显),
|
||
/// 转发时**不按它过滤**——过滤要靠读请求体,而 access 阶段读不到。
|
||
/// 供应商侧自己会拒绝不认识的参数,拦在网关意义不大。
|
||
#[serde(default)]
|
||
pub params: Vec<String>,
|
||
#[serde(default = "default_true")]
|
||
pub enabled: bool,
|
||
#[serde(default)]
|
||
pub note: String,
|
||
/// 调用语法提示(**机器可读**的描述字段,专为 passthrough / 复杂 vendor 设计)。
|
||
///
|
||
/// 为什么需要:`/api/v1/me` 把这条发给用户 AI 后,AI 必须能**自己拼出**调用语法——
|
||
/// 路径尾部是什么、什么 Content-Type、上游 Swagger 在哪。`desc` 是中文给运维看的,
|
||
/// `params` 只对 vendor 有意义,对 passthrough 是空数组,没法告诉 AI 怎么调。
|
||
/// `usage_hint` 是管理员按建议格式(自由文本)填写的结构化提示,AI 直接解析。
|
||
///
|
||
/// 不进 shm:热路径只查 base/key/asset_id/mode,`usage_hint` 只在管理台 +
|
||
/// `/api/v1/me` 拉清单时回显,进 shm 反而占带宽。
|
||
///
|
||
/// 建议格式(OpenAPI 风格):
|
||
/// ```text
|
||
/// POST /<tail> multipart, fields=[file]; OCR 上传图片
|
||
/// POST /<tail>/base64 json, {image_base64:string}
|
||
/// POST /<tail>/url?url=<dst> json, {}
|
||
/// Swagger: http://192.168.1.11:9003/docs
|
||
/// ```
|
||
#[serde(default)]
|
||
pub usage_hint: String,
|
||
#[serde(default)]
|
||
pub created_at: i64,
|
||
}
|
||
|
||
fn default_true() -> bool {
|
||
true
|
||
}
|
||
|
||
/// 默认代理模式 = vendor(向后兼容旧数据:没有 `mode` 字段的条目就是 vendor)。
|
||
fn default_mode() -> String {
|
||
"vendor".to_owned()
|
||
}
|