facet-models 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. facet_models-1.0.0/LICENSE +21 -0
  2. facet_models-1.0.0/PKG-INFO +411 -0
  3. facet_models-1.0.0/README.md +388 -0
  4. facet_models-1.0.0/pyproject.toml +50 -0
  5. facet_models-1.0.0/setup.cfg +4 -0
  6. facet_models-1.0.0/src/facet/__init__.py +24 -0
  7. facet_models-1.0.0/src/facet/__main__.py +8 -0
  8. facet_models-1.0.0/src/facet/_find.py +98 -0
  9. facet_models-1.0.0/src/facet/_identity.py +37 -0
  10. facet_models-1.0.0/src/facet/_table.py +73 -0
  11. facet_models-1.0.0/src/facet/cli.py +110 -0
  12. facet_models-1.0.0/src/facet/data/model-registry.json +1 -0
  13. facet_models-1.0.0/src/facet/gateway/__init__.py +11 -0
  14. facet_models-1.0.0/src/facet/gateway/_alias.py +20 -0
  15. facet_models-1.0.0/src/facet/gateway/accounts.py +195 -0
  16. facet_models-1.0.0/src/facet/gateway/ark_quota.py +360 -0
  17. facet_models-1.0.0/src/facet/gateway/audit.py +110 -0
  18. facet_models-1.0.0/src/facet/gateway/bailian_quota.py +226 -0
  19. facet_models-1.0.0/src/facet/gateway/cli.py +168 -0
  20. facet_models-1.0.0/src/facet/gateway/completions.py +145 -0
  21. facet_models-1.0.0/src/facet/gateway/convert.py +689 -0
  22. facet_models-1.0.0/src/facet/gateway/core.py +1737 -0
  23. facet_models-1.0.0/src/facet/gateway/deepseek_quota.py +54 -0
  24. facet_models-1.0.0/src/facet/gateway/dsh.py +365 -0
  25. facet_models-1.0.0/src/facet/gateway/facts.py +100 -0
  26. facet_models-1.0.0/src/facet/gateway/freealign.py +336 -0
  27. facet_models-1.0.0/src/facet/gateway/hunyuan_quota.py +142 -0
  28. facet_models-1.0.0/src/facet/gateway/keys.py +178 -0
  29. facet_models-1.0.0/src/facet/gateway/maintenance.py +1727 -0
  30. facet_models-1.0.0/src/facet/gateway/minimax_quota.py +197 -0
  31. facet_models-1.0.0/src/facet/gateway/modelscope_quota.py +155 -0
  32. facet_models-1.0.0/src/facet/gateway/moonshot_quota.py +75 -0
  33. facet_models-1.0.0/src/facet/gateway/notifier.py +400 -0
  34. facet_models-1.0.0/src/facet/gateway/opencode_quota.py +89 -0
  35. facet_models-1.0.0/src/facet/gateway/openrouter_quota.py +84 -0
  36. facet_models-1.0.0/src/facet/gateway/persistence.py +180 -0
  37. facet_models-1.0.0/src/facet/gateway/probe.py +384 -0
  38. facet_models-1.0.0/src/facet/gateway/providers.json +511 -0
  39. facet_models-1.0.0/src/facet/gateway/providers.py +446 -0
  40. facet_models-1.0.0/src/facet/gateway/quota.py +147 -0
  41. facet_models-1.0.0/src/facet/gateway/report.py +236 -0
  42. facet_models-1.0.0/src/facet/gateway/responses.py +411 -0
  43. facet_models-1.0.0/src/facet/gateway/seed.py +108 -0
  44. facet_models-1.0.0/src/facet/gateway/server.py +6160 -0
  45. facet_models-1.0.0/src/facet/gateway/static/app.js +5530 -0
  46. facet_models-1.0.0/src/facet/gateway/static/index.html +1086 -0
  47. facet_models-1.0.0/src/facet/gateway/static/setup.js +713 -0
  48. facet_models-1.0.0/src/facet/gateway/static/style.css +601 -0
  49. facet_models-1.0.0/src/facet/gateway/subscriptions.py +333 -0
  50. facet_models-1.0.0/src/facet/gateway/tokenhub_quota.py +255 -0
  51. facet_models-1.0.0/src/facet/gateway/ui.py +946 -0
  52. facet_models-1.0.0/src/facet/gateway/usage.py +337 -0
  53. facet_models-1.0.0/src/facet/gateway/watch.py +627 -0
  54. facet_models-1.0.0/src/facet/gateway/zhipu_quota.py +195 -0
  55. facet_models-1.0.0/src/facet/py.typed +0 -0
  56. facet_models-1.0.0/src/facet_models.egg-info/PKG-INFO +411 -0
  57. facet_models-1.0.0/src/facet_models.egg-info/SOURCES.txt +93 -0
  58. facet_models-1.0.0/src/facet_models.egg-info/dependency_links.txt +1 -0
  59. facet_models-1.0.0/src/facet_models.egg-info/entry_points.txt +5 -0
  60. facet_models-1.0.0/src/facet_models.egg-info/top_level.txt +1 -0
  61. facet_models-1.0.0/tests/test_package.py +302 -0
  62. facet_models-1.0.0/tests/test_pick_model.py +124 -0
  63. facet_models-1.0.0/tests/test_planrouter.py +1215 -0
  64. facet_models-1.0.0/tests/test_planrouter_ark_quota.py +454 -0
  65. facet_models-1.0.0/tests/test_planrouter_bailian_hunyuan_quota.py +365 -0
  66. facet_models-1.0.0/tests/test_planrouter_billing.py +137 -0
  67. facet_models-1.0.0/tests/test_planrouter_catalog.py +802 -0
  68. facet_models-1.0.0/tests/test_planrouter_compat.py +690 -0
  69. facet_models-1.0.0/tests/test_planrouter_convert.py +615 -0
  70. facet_models-1.0.0/tests/test_planrouter_credentials.py +296 -0
  71. facet_models-1.0.0/tests/test_planrouter_dsh.py +255 -0
  72. facet_models-1.0.0/tests/test_planrouter_e2e.py +261 -0
  73. facet_models-1.0.0/tests/test_planrouter_facts.py +221 -0
  74. facet_models-1.0.0/tests/test_planrouter_freealign.py +1129 -0
  75. facet_models-1.0.0/tests/test_planrouter_maintenance.py +1773 -0
  76. facet_models-1.0.0/tests/test_planrouter_models.py +352 -0
  77. facet_models-1.0.0/tests/test_planrouter_observability.py +379 -0
  78. facet_models-1.0.0/tests/test_planrouter_ops.py +389 -0
  79. facet_models-1.0.0/tests/test_planrouter_probe.py +481 -0
  80. facet_models-1.0.0/tests/test_planrouter_providers.py +498 -0
  81. facet_models-1.0.0/tests/test_planrouter_providers_api.py +237 -0
  82. facet_models-1.0.0/tests/test_planrouter_quota_report.py +478 -0
  83. facet_models-1.0.0/tests/test_planrouter_responses.py +381 -0
  84. facet_models-1.0.0/tests/test_planrouter_routes_macro.py +110 -0
  85. facet_models-1.0.0/tests/test_planrouter_scoring.py +260 -0
  86. facet_models-1.0.0/tests/test_planrouter_seed.py +117 -0
  87. facet_models-1.0.0/tests/test_planrouter_state.py +304 -0
  88. facet_models-1.0.0/tests/test_planrouter_subs.py +349 -0
  89. facet_models-1.0.0/tests/test_planrouter_tokenhub_quota.py +187 -0
  90. facet_models-1.0.0/tests/test_planrouter_ui.py +350 -0
  91. facet_models-1.0.0/tests/test_planrouter_vendor_binding.py +314 -0
  92. facet_models-1.0.0/tests/test_planrouter_watch.py +853 -0
  93. facet_models-1.0.0/tests/test_sync.py +282 -0
  94. facet_models-1.0.0/tests/test_verify.py +615 -0
  95. facet_models-1.0.0/tests/test_weekly_maintenance.py +130 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Facet contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,411 @@
1
+ Metadata-Version: 2.4
2
+ Name: facet-models
3
+ Version: 1.0.0
4
+ Summary: Self-maintaining LLM gateway over free-tier quotas, with a bundled model facts table. Zero runtime dependencies. / 自维护的免费额度聚合网关,内置模型事实表,零运行时依赖。
5
+ Author: Facet contributors
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/hsliuping/Facet
8
+ Keywords: llm,model-registry,model-selection,ai,facts,gateway,free-tier,router
9
+ Classifier: Development Status :: 5 - Production/Stable
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: Operating System :: OS Independent
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Topic :: Software Development :: Libraries
18
+ Classifier: Typing :: Typed
19
+ Requires-Python: >=3.10
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Dynamic: license-file
23
+
24
+ # Facet
25
+
26
+ **Facet 是一个自维护的 LLM 免费额度聚合网关:把你手里各家厂商的免费额度聚合成一个 OpenAI / Anthropic 兼容端点,并每天自己探测、修复、汇报。**
27
+
28
+ > Facet 最初是一张"模型事实表"。它现在长成了完整的产品:**网关是主体**,事实表退居为配套的数据层(见文末)。
29
+
30
+ ## 为什么需要它
31
+
32
+ 免费额度很散:智谱、火山引擎、阿里百炼、魔搭、NVIDIA NIM、OpenRouter `:free`……每家协议不同、密钥不同、限额规则不同,逐家接入、逐家盯梢的成本远超额度本身的价值。
33
+
34
+ 这尤其是个人和小团队的日常:额度自己申请、agent 自己写、没有平台团队替你
35
+ 盯渠道。企业级网关(要配数据库、集群、专职运维)在这个量级上是杀鸡用牛刀。
36
+
37
+ Facet 把它们收敛成三件事:
38
+
39
+ - **一个端点、一把密钥**——下游 agent 只接 Facet,不必逐家对接;
40
+ - **一个控制台**——渠道、路由、请求日志、配额、维护,全在浏览器里;
41
+ - **一套自动运维**——探测、冷却、目录修复、维护报告,按周期自动跑。
42
+
43
+ ## 特点
44
+
45
+ - **适合个人和小团队**——单进程、单配置文件、状态与日志全部落盘为普通
46
+ 文件:无数据库、无外部中间件,一个 Python 进程或一个容器就是全部部署,
47
+ 一台最小的机器即可自托管。
48
+ - **零依赖**——纯 Python 标准库实现,`pip` 装完即用,不拖任何第三方运行时包。
49
+ - **零配置可跑**——没有 `router.json` 也能启动:自动种子化免费层模板
50
+ 渠道,进控制台填 key 启用就能用。
51
+ - **双协议全兼容**——OpenAI 与 Anthropic 两套 API 同端口并存,下游改个
52
+ `base_url` 就完成迁移。
53
+ - **品牌模型名**——`facet-auto` / `facet-cheap` / `facet-free` / `facet-agent`
54
+ / `facet-embedding`,语义即路由,下游不感知任何上游模型 id。
55
+ - **自维护**——每天自动探测冷却渠道、修复目录漂移、刷新厂家清单,产出
56
+ 「已应用 / 建议 / 告警」三桶报告,绝不自动应用未经目录确认的变更。
57
+ - **免费优先**——免费池答题验证队列、`$free` 宏、免费渠道轮转;维护调用
58
+ 绝不烧付费额度。
59
+ - **全程可追溯**——每次选型打印一行 `[route]` 日志:mode / reason / sticky /
60
+ rotate / lb / picked,决策过程完整可复盘。
61
+ - **状态可恢复**——冷却、粘滞、负载均衡打分与按天用量全部落盘,重启不丢。
62
+
63
+ ## 功能清单
64
+
65
+ | 类别 | 功能 |
66
+ |---|---|
67
+ | API 端点 | OpenAI 兼容:`/v1/chat/completions`、`/v1/completions`、`/v1/responses`、`/v1/embeddings`、`/v1/rerank`、`/v1/audio/speech`、`/v1/audio/transcriptions`、`/v1/audio/translations`;Anthropic 兼容:`/v1/messages`、`/v1/messages/count_tokens`(本地估算,不调上游);`GET /v1/models` |
68
+ | 流式 | SSE 流式透传(chat 与 messages) |
69
+ | 路由 | `(protocol, hint) → 渠道链`;品牌名映射;`default` 回退;`$free` 宏;同优先级轮转 |
70
+ | 负载均衡 | `order` 链式 / `weighted` 打分(成功率 + 错误 + 延迟 EWMA);会话粘滞 30 分钟 |
71
+ | 容错 | 配额/错误触发冷却;HealthProber 指数退避探活(30s → 300s);额度恢复自动复活 |
72
+ | 自我维护 | 每日目录刷新、自动修复(先备份)、订阅/厂家清单刷新、LLM 顾问意见、三桶报告、维护 API |
73
+ | 免费池 | tier=free 渠道捐候选、合成测验验证、复验除名、冷却兜底 |
74
+ | 控制台 | 渠道/路由编辑、API Key 与管理员密钥管理、请求日志、维护日志、接入文档、热加载 |
75
+ | 认证 | 多成员 API Key、管理员密钥、`env:VAR` 密钥引用(明文不落配置) |
76
+ | 运营 | 按天用量统计、订阅到期提醒、通知投递、请求审计日志(`requests.jsonl`)、渠道出站代理 |
77
+
78
+ ## 安装
79
+
80
+ 需要 Python 3.10+(Windows 安装包与 macOS/Linux 一键脚本会自动处理,无需自备)。网关与事实表都是纯标准库实现,**零第三方依赖**。
81
+
82
+ - Windows:Inno Setup 安装包(含托盘、开机自启),本地 `python tools/build_windows.py` 构建;
83
+ - macOS / Linux:见下方一键安装小节(缺失或过旧时自动装 Python:Homebrew/系统包管理器 → 独立 CPython 兜底);
84
+ - 容器:见下文[「Docker 部署」](#docker-部署)。
85
+
86
+ ```bash
87
+ pip install facet-models # PyPI 包名沿用历史名,装出来的命令是 facet
88
+ ```
89
+
90
+ 或从源码安装:
91
+
92
+ ```bash
93
+ git clone https://github.com/hsliuping/Facet && cd Facet
94
+ pip install -e .
95
+ ```
96
+
97
+ ### macOS 一键安装(launchd 服务)
98
+
99
+ ```bash
100
+ git clone https://github.com/hsliuping/Facet && cd Facet
101
+ tools/macos/install.sh # venv 装到 ~/.facet,注册开机自启 + 崩溃重启
102
+ ```
103
+
104
+ - 装完自动做健康检查并打印控制台地址;服务崩溃后 launchd 自动拉起。
105
+ - **无需自备 Python**:缺失或版本过旧时自动安装(Homebrew → 独立 CPython 兜底,
106
+ 铺到 `~/.facet/python`,不碰系统环境)。
107
+ - 配置与日志在 `~/.facet/`(`data/router.json`、`logs/gateway.err.log`)。
108
+ - 自定义:`FACET_HOME`/`FACET_PORT`/`FACET_HOST` 环境变量,或 `install.sh <路径|git URL>` 换安装源。
109
+ - 卸载:`tools/macos/uninstall.sh`(数据保留;`--purge` 连 `~/.facet` 一起删)。
110
+
111
+ ### Linux 一键安装(systemd 服务)
112
+
113
+ ```bash
114
+ git clone https://github.com/hsliuping/Facet && cd Facet
115
+ tools/linux/install.sh # venv 装到 ~/.facet,注册开机自启 + 崩溃自动重启
116
+ ```
117
+
118
+ - 无需自备 Python:缺 3.10+ 或系统仓库版本过旧(如 Ubuntu 20.04 / CentOS 7)时自动安装——先用包管理器,装不上再自动铺独立 CPython 到 `~/.facet/python`,不碰系统环境。
119
+ - 装完自动做健康检查并打印控制台地址;服务崩溃后 systemd 自动拉起。
120
+ - 配置与数据在 `~/.facet/`(`data/router.json`);日志:`journalctl -u facet -f`。
121
+ - 自定义:`FACET_HOME`/`FACET_PORT`/`FACET_HOST` 环境变量,或 `install.sh <路径|git URL>` 换安装源。
122
+ - 卸载:`tools/linux/uninstall.sh`(数据保留;`--purge` 连 `~/.facet` 一起删)。
123
+
124
+ 容器部署见下文[「Docker 部署」](#docker-部署)。
125
+
126
+ ## 快速开始
127
+
128
+ ```bash
129
+ facet serve # 默认监听 127.0.0.1:8787
130
+ ```
131
+
132
+ - **首启引导**:没有 `router.json` 时自动生成种子配置(仅含禁用的免费层模板渠道:NVIDIA NIM / Google AI Studio / Z.AI),需注册 Key 后在控制台启用。
133
+ - 浏览器打开 `http://127.0.0.1:8787/` 进入控制台;管理密钥首次启动随机生成,
134
+ 只在启动日志里打印一次(打开控制台时填入,之后可在「管理密钥」页换成自己的值)。
135
+ - 全新环境会自动弹出「新手配置向导」(右上角「快速开始」可随时重开):
136
+ 设置管理密码 → 选厂家填 Key(自动测试连通,火山/百炼可一并填 AK/SK 供免费额度对齐)
137
+ → 生成调用密钥,一路走完即可路由。
138
+ - 也可以跳过向导,在渠道页给模板渠道填入各厂家的 key 并启用,保存后即可路由。
139
+
140
+ 用 curl 验证(`facet-free` 只走免费渠道,同优先级轮转):
141
+
142
+ ```bash
143
+ curl http://127.0.0.1:8787/v1/chat/completions \
144
+ -H "Authorization: Bearer <listen.api_key>" \
145
+ -H "Content-Type: application/json" \
146
+ -d '{"model": "facet-free", "messages": [{"role": "user", "content": "你好"}]}'
147
+ ```
148
+
149
+ 常用检查:
150
+
151
+ ```bash
152
+ curl http://127.0.0.1:8787/health # 健康与渠道冷却状态
153
+ curl http://127.0.0.1:8787/stats # 用量统计
154
+ curl http://127.0.0.1:8787/v1/models # 网关侧模型清单
155
+ facet serve --check # 校验配置、打印路由链,不启动服务
156
+ ```
157
+
158
+ ## Docker 部署
159
+
160
+ ```bash
161
+ docker compose up -d # 控制台 http://localhost:8787(ROUTER_PORT 可改)
162
+ ```
163
+
164
+ - 首次运行自带一个 mock 假上游做冒烟测试(`ROUTER_SEED=example`)。真实使用
165
+ 时:停掉服务 → 删除 `./data/router.json` → 去掉该环境变量,下次启动会
166
+ 种子化厂家预置渠道,随后删掉 compose 里的 `mock` 服务即可。
167
+ - 配置、状态、日志都落在宿主机 `./data/`(bind mount)。改了
168
+ `./data/router.json` 后 `POST /api/reload` 热加载,或直接在控制台编辑。
169
+ - 密钥经环境变量注入:`ROUTER_API_KEY`、`ROUTER_ADMIN_KEY`;未设置
170
+ `ROUTER_ADMIN_KEY` 时,entrypoint 会在首启生成随机管理密钥并打印在容器日志
171
+ (`docker compose logs router`)。火山引擎 IAM
172
+ AK/SK 用 `VOLC_ACCESSKEY` / `VOLC_SECRETKEY`(也可在控制台渠道编辑器里填,
173
+ UI 配置优先)。
174
+
175
+ ## 服务化运行
176
+
177
+ `facet serve` 的完整参数:
178
+
179
+ | 参数 | 默认 | 说明 |
180
+ |---|---|---|
181
+ | `--config` | `router.json` | 渠道配置文件路径 |
182
+ | `--host` / `--port` | `127.0.0.1:8787` | 监听地址;绑非回环地址必须配 `listen.api_key` |
183
+ | `--check` | — | 校验配置并打印路由链后退出,不启动服务 |
184
+ | `--keys-file` | 配置旁 `keys.json` | 成员 API key 存储 |
185
+ | `--state-file` | 配置旁 `router.state.json` | 冷却与负载均衡状态(重启恢复) |
186
+ | `--usage-file` | 配置旁 `usage.json` | 按天用量 |
187
+ | `--audit-file` | 配置旁 `requests.jsonl` | 请求路由审计日志 |
188
+ | `--subscriptions` | 配置旁 `subscriptions.json` | 订阅套餐记录(到期提醒) |
189
+ | `--notifications-file` | 配置旁 `notifications.json` | 提醒投递记录 |
190
+
191
+ ## 认证
192
+
193
+ - **`listen.api_key`**——调用 `/v1/*` 与 `/api/*` 的成员密钥;支持
194
+ `env:VAR` 写法从环境变量读取,明文不落配置。控制台「API Keys」可为每个
195
+ 成员签发独立 key。
196
+ - **`listen.admin_key`**——管理面密钥;没有内置默认密码:首次启动会随机生成
197
+ 并在日志里打印一次。已配置 `api_key` 但未设置 `admin_key` 时管理接口直接
198
+ 拒绝(401),`--check` 会提醒;登录控制台后可在「管理密钥」里换成自己的值。
199
+
200
+ ### 升级:管理密钥改为随机生成
201
+
202
+ 本版本移除了内置默认管理密码 `admin`(硬编码凭据,CWE-798)。管理接口的
203
+ 行为按凭据状态分三种:
204
+
205
+ | 配置状态 | 管理接口行为 |
206
+ |---|---|
207
+ | `listen.admin_key` 已设置 | 只认这个密钥 |
208
+ | `api_key`、`admin_key` 都未设置 | 控制台开放(默认仅监听 `127.0.0.1`) |
209
+ | `api_key` 已设置、`admin_key` 未设置 | **锁定**,管理接口一律返回 401 |
210
+
211
+ 全新安装不受影响:首启自动随机生成密钥。**旧版本升级、且原来一直用默认
212
+ `admin` 登录的部署**,按下面步骤补齐密钥(旧配置不会被静默改写):
213
+
214
+ 1. 先检查状态:
215
+
216
+ ```bash
217
+ facet serve --check
218
+ ```
219
+
220
+ 出现 `WARNING: listen.admin_key is unset while listen.api_key is set`
221
+ 即说明管理接口已锁定。
222
+ 2. 在 `router.json` 的 `listen` 块里显式写入 `admin_key`(想让密钥只走环境
223
+ 变量、不落盘,就写 `"admin_key": "env:ROUTER_ADMIN_KEY"`):
224
+
225
+ ```json
226
+ { "listen": { "api_key": "…", "admin_key": "你的管理密钥" } }
227
+ ```
228
+
229
+ 3. 重启 `facet serve` 生效。注意管理接口处于锁定状态时无法调用
230
+ `POST /api/reload` 热加载(它也要鉴权),所以此处只能重启。
231
+ 4. 重新打开控制台,右上角「管理密钥」会要求填入刚设置的密钥,填入即可正常
232
+ 管理;之后可在「管理密钥」页面里再验证旧值、换成自己的值。
233
+
234
+ Docker 部署同理:
235
+
236
+ - 已有 `./data/router.json`:停掉容器,在 `compose.yaml` 旁的 `.env` 里设置
237
+ `ROUTER_ADMIN_KEY=<你的密钥>` 再 `docker compose up -d`。此前依赖 compose
238
+ 默认值 `admin` 的部署必须补这一步,否则管理接口会锁定(配置文件里是
239
+ `env:` 引用,entrypoint 不会改写已存在的配置);也可以直接改
240
+ `./data/router.json` 里的 `listen.admin_key`。
241
+ - 全新部署(还没有 `./data/router.json`):不设置 `ROUTER_ADMIN_KEY` 时,
242
+ entrypoint 会生成随机密钥并打印在首启日志里。
243
+
244
+ 以上各场景可直接复制的完整配置片段(明文 / `env:` 引用 / `.env` 文件 /
245
+ 验证命令)见 [docs/upgrade-keys-examples.md](docs/upgrade-keys-examples.md)。
246
+
247
+ 下游 agent 的完整接入指南(端点、模型命名、错误码、SDK 示例):
248
+ [docs/agent-integration.md](docs/agent-integration.md)(控制台「数据 → 接入文档」页面可直接阅读)。
249
+
250
+ ## 下游 agent 怎么用
251
+
252
+ OpenAI 兼容端点族(`/v1/chat/completions`、`/v1/responses`、`/v1/embeddings`
253
+ 等,见上文功能清单)与 Anthropic 兼容端点族(`/v1/messages` 及
254
+ `count_tokens`)同端口并存,`GET /v1/models` 列出网关侧的可用模型名。
255
+
256
+ ### 品牌模型名
257
+
258
+ 不必记住任何上游 id——用 Facet 的品牌名,语义即路由:
259
+
260
+ | 模型名 | 语义 |
261
+ |---|---|
262
+ | `facet-auto` | 按路由链自动挑渠道 |
263
+ | `facet-cheap` | 优先低成本渠道 |
264
+ | `facet-free` | 只走免费渠道(`$free` 宏展开的全部 tier=free 渠道,同优先级轮转) |
265
+ | `facet-agent` | agent 任务预排序队列 |
266
+ | `facet-embedding` | 嵌入模型路由 |
267
+
268
+ 也接受上游原始模型名(如 `deepseek-v3.2`)——命中哪个渠道由路由表决定。
269
+
270
+ ### 会话粘滞
271
+
272
+ 请求带 `X-Session-Id` 头(或请求体 `user` / `metadata.user_id` 字段)即启用
273
+ 会话亲和:同一会话 30 分钟内粘在同一渠道,避免上下文在不同供应商之间漂移。
274
+
275
+ ## 核心机制
276
+
277
+ ### 路由与选型
278
+
279
+ - 路由表是 `(protocol, hint) → 渠道链` 的映射;品牌模型名映射为路由提示
280
+ (`facet-free` → `free`),没命中提示路由时回退到该协议的 `default` 路由。
281
+ - 渠道链按 `priority` 升序排列,跳过禁用与冷却中的渠道;`$free` 宏展开为
282
+ **所有启用的 tier=free 渠道**(按优先级、名称排序),不用逐个列名。
283
+ - 每次选型打印一行 `[route]` 日志,整个决策过程可追溯:
284
+
285
+ ```
286
+ [route] openai:free model='facet-free' mode=auto reason=internal-model-name sticky=no rotate=1/4 lb=order skipped=- picked=free-tier->nvidia/nemotron-3.5-lightning:free chain=...
287
+ ```
288
+
289
+ ### 负载均衡与容错
290
+
291
+ - `lb_strategy`:`order`(链式顺序)或 `weighted`(按成功率、错误次数、
292
+ 延迟 EWMA 打分排序);同优先级段内轮转(round-robin)。
293
+ - 配额耗尽 / 上游报错触发冷却;后台 HealthProber 对冷却渠道按指数退避
294
+ (30s → 300s)探活,额度恢复自动复活。
295
+ - 有会话粘滞时优先粘住的渠道,粘滞过期或渠道冷却后才重新选型。
296
+
297
+ ### 自我维护
298
+
299
+ 启动约 2 分钟后先跑一次,之后每 `defaults.maintenance_hours`(默认 24;
300
+ `0` 关闭)跑一次。一次运行:刷新渠道目录 → 自动应用目录可确认的修复
301
+ (先备份配置)→ 刷新订阅套餐模型与厂家注册表 → 请维护 LLM 写顾问意见 →
302
+ 落一份报告。每条发现只落进三个桶之一:
303
+
304
+ | 桶 | 含义 | 谁来处理 |
305
+ |---|---|---|
306
+ | `applied` | 目录可确认(上游下架模型、`auto` 重指向、套餐/厂家模型清单刷新) | 无人——已自动应用,且有配置备份 |
307
+ | `suggestions` | 值得做但目录无法确认(上游新模型、反复配额冷却、LLM 意见——仅供参考,绝不自动应用) | 你——控制台一键采纳 |
308
+ | `alerts` | 密钥失效、目录为空、抓取失败 | 你,线下处理 |
309
+
310
+ 报告保留在内存(最近 20 份)并追加到配置旁的 `maintenance.jsonl`,重启不丢。
311
+ 同样的数据也是普通 HTTP:
312
+
313
+ ```bash
314
+ GET /api/maintenance # 当前状态:开关、周期、模型池、上次运行
315
+ GET /api/maintenance/logs/50 # 运行历史,最新在前
316
+ POST /api/maintenance/run # 立即手动跑一次
317
+ POST /api/maintenance/test-models # 重新测验免费池,重建队列
318
+ POST /api/maintenance/apply # 采纳建议({"channel", "models"})
319
+ ```
320
+
321
+ ### 免费池
322
+
323
+ `defaults.maintenance_model` 留空或设为 `auto` 时,所有维护 LLM 调用都跑在
324
+ 一个「已验证免费模型队列」上,而不是钉死某个 id:
325
+
326
+ - 只有显式标记 `tier: "free"` 的渠道捐出候选——探测绝不烧付费额度。
327
+ - 候选要过一道测验:合成的文档页 + 已知标准答案,全对的进队列。队列持久化
328
+ 在配置旁的 `maintenance_models.json`,每次探测都重新复验;真干活时掉链子
329
+ 的模型当场除名。探测有冷却兜底,全灭的免费池不会把维护变成探测风暴。
330
+
331
+ `defaults.maintenance_model` 写显式 id(逗号/空白分隔)则绕过免费池,原样使用。
332
+
333
+ ### 维护调用走直达,不走路由
334
+
335
+ 维护模型的 id 是上游 id,所以按上游的方式寻址:直接打到第一个在自己的
336
+ models 映射里暴露它的启用渠道(tier-`free` 优先,其余按配置顺序),单轮
337
+ 非流式。路由表从不参与;维护不许依赖路由成员。只有没有任何渠道暴露的
338
+ 品牌 id(如 `facet-auto`)才回退为经网关自身的 loopback 调用。
339
+
340
+ ### 渠道出站代理
341
+
342
+ 渠道可带 `proxy: "http://..."`(明文 URL 或密钥引用)。该渠道名下的所有
343
+ 上游请求——转发流量与维护直达调用——都走它;不填则直连。
344
+
345
+ ## 配置
346
+
347
+ 一切围绕一份 `router.json`(示例见 [data/router.example.json](data/router.example.json)):
348
+
349
+ - **channels**——上游渠道:`name`、`protocol`(`openai` / `anthropic`)、
350
+ `base_url`、`api_key`(支持密钥引用)、`models`(模型映射,`"auto"` 指向
351
+ 目录拉取)、`priority`、`tier`(`free` / `paid`)、`proxy`。
352
+ - **routes**——`(protocol, hint) → 渠道链`;渠道名支持 `$free` 宏。
353
+ - **defaults**——负载均衡策略、探活节奏、粘滞 TTL、维护周期与维护模型等。
354
+ - **listen**——`host`、`port`、`api_key`、`admin_key`。
355
+
356
+ 厂家接入元数据在内置 `src/facet/gateway/providers.json` + 用户覆盖层
357
+ (配置目录下的 `providers.json`,按 id 整体替换内置条目)。给内置表提 PR
358
+ 或本地放一条覆盖条目皆可。维护每天刷新厂家模型清单,变更带备份持久化进
359
+ 覆盖文件。
360
+
361
+ ## 控制台
362
+
363
+ 与网关同端口(`http://127.0.0.1:8787/`),浏览器即用:渠道与路由管理、
364
+ API Key 与管理员密钥、请求日志、维护日志、接入文档。所有 `/api/*` 接口与
365
+ 页面同源,可用同一把管理员密钥脚本化。
366
+
367
+ ## 事实表(配套数据层)
368
+
369
+ `registry/model-registry.json`——单文件 < 1 MB,覆盖 217 个 provider、
370
+ 约 2,400 个模型的能力、限制与价格,每周从
371
+ [models.dev](https://models.dev) + [OpenRouter](https://openrouter.ai/api/v1/models)
372
+ 同步(GitHub Action 自动开 PR),质量门与字段标准见
373
+ [schema/model-registry.schema.json](schema/model-registry.schema.json)。
374
+
375
+ 事实表既可以独立使用(读表 → 自己的规则 → 自己决策):
376
+
377
+ ```python
378
+ import facet
379
+
380
+ t = facet.load() # 包内捆绑快照
381
+ facet.resolve(t, "glm-5.3") # -> 规范键,容忍拼写漂移
382
+ facet.find(t, tool_call=True, min_context=200_000, free=True, limit=10)
383
+ ```
384
+
385
+ ```bash
386
+ facet "glm-5.3" # 解析并显示一个模型的事实
387
+ facet --free --tools --limit 10 # 按条件筛选免费模型
388
+ ```
389
+
390
+ 也可以作为网关的配套:网关用它做名字解析与 `--free` 新手指引。网关的**路由
391
+ 只看维护层观测到的渠道状态**,绝不依赖表的新鲜度——两层之间只有这一座桥。
392
+
393
+ ## 开发
394
+
395
+ ```bash
396
+ python -m pytest tests/ -q # 全量回归(单元/接口测试)
397
+ python -m pytest tests/web/test_smoke.py -v --tb=short # Web UI 冒烟测试(Playwright,需自行启动 gateway)
398
+ python tools/sync_models_dev.py # models.dev -> 事实表(每周或按需)
399
+ python tools/validate_registry.py # 事实表质量门(体积、null、结构、数量)
400
+ python tools/verify_claims.py gpt-5 --dry-run # 实测验证模型能力声明
401
+ ```
402
+
403
+ ## 非目标
404
+
405
+ 事实表不做路由、不管 API key、不采集遥测、不做逐请求排序、不聚合跑分。
406
+ 网关层做路由,但只依据维护层观测到的渠道状态,从不依赖表的新鲜度。
407
+
408
+ ## 治理
409
+
410
+ MIT 许可。贡献须接受 [docs/CLA.md](docs/CLA.md) 中的协议,流程见
411
+ [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)。