pipeline-llm/README.md

pipeline-llm — 产线平台模型治理模块

产线平台的模型层：供应商/账号/模型治理 + 组织容错策略 + 限额限流 + 双维度记账。 所有表 llm_ 前缀，建在宿主应用库（pipeline）。

模块定位

解决五类问题：

1. 供给侧治理：供应商协议+全球端点目录、账号（钱包）、模型注册、适配模板
2. 容量治理：供应商限流 → 多账号轮转；多供应商 → 主备模型容错
3. 需求侧治理：组织级模型容错策略、组织限额限流、个人限额限流
4. 计费：双维度记账（成本侧记账号、消费侧记组织/个人），模型挂定价 pricing_program.ppid
5. 端点选择：端点目录配在供应商下（全球配置一次），账号选用端点，客户按区域偏好（prefer/must）

数据表（8 张）

表	说明
llm_vendor	供应商（协议 + 端点目录 JSON）
llm_account	供应商账号（钱包：余额/充值/选端点，api_key AES 加密）
llm_model	模型注册（能力分类/挂定价 ppid/成本售价，name 唯一）
llm_api_profile	适配模板（协议×能力形态去重）
llm_org_policy	组织容错策略（主备模型 + 端点偏好）
llm_org_quota	组织限额限流（池余额 + QPM）
llm_user_quota	个人限额限流（额度上限 + QPM）
llm_usage	用量流水（双维度记账事实表）

调用门禁链

① 个人限流 → ② 组织限流 → ③ 个人额度 → ④ 组织池(预授权)
→ ⑤ 组织策略选模型(主→备) → ⑥ 账号×端点候选池(偏好过滤+余额加权+冷却避让)
→ ⑦ 调用 → ⑧ 结算(实际用量，多退少补，双维度记账)

任何一级不过：快速失败 + 明确中文原因（不挂起、不静默）。

集成方式（复用不改建）

模块只提供治理引擎与配置管理；实际 LLM 转发仍由宿主已有的 pipeline_service.llm_bridge / llm_proxy 承担，在两处挂钩子：

• llm_bridge._get_model_config：治理启用时前置解析（主备容错+端点选择）
• llm_proxy.proxy_chat_completion：调用前后接门禁与结算（运行环境 token 路径）

机构未配置治理（无策略、无新模型）→ 返回 __LEGACY__，调用方回退旧 llm 表，向后兼容。

宿主接入清单

1. app/pipeline_app.py init() 加 load_llm()（try/except ImportError 兜底）
2. build.sh：clone 枚举 + pip install 枚举 + CRUD 生成枚举 + wwwroot 符号链接枚举
3. scripts/create_tables.py：IDE 幂等建表枚举加 pipeline-llm（或执行本模块 mysql.ddl.sql）
4. scripts/import_init.py：INIT_MODULES 加本模块 init/data.json（appcodes 字典）
5. conf/rp.json：/pipeline-llm/** 注册到 logined；运行 scripts/load_path.py
6. wwwroot/index.ui 主菜单加「模型治理」项（URL /pipeline-llm）
7. restart-pipeline.sh 重启（.py 变更必须重启；api_key 有缓存，改 key 也须重启）

关键约定

• api_key 用 AES 单层加密（appPublic.aes.aes_encode_b64，password_key 做密钥）。 ⚠️ 不用 RC4：password()/unpassword() 盐不对称，加密后永久不可解。
• 限流用 Redis 分钟窗口原子计数（db4，与会话 db3 隔离）；Redis 故障时限流放行（fail-open）， 余额仍由 DB 条件 UPDATE 守住。
• 429 → (账号,端点)对冷却 60s；账号级冷却用 * 通配键。
• 双维度记账：一次调用同行记 cost（成本侧，账号余额扣）+ charge（消费侧，组织池扣）； 充值是 status=recharge 行（对账用）。
• 预授权-结算：调用前按预估冻结，调用后按实际 token 多退少补。

文档

• docs/design-spec.md — 完整设计规范（架构/表/机制/功能点/分期）
• docs/test-cases.md — 测试用例（30 例，部署后全部执行）

开发日志

见 docs/work-log-2026-09-01.md。