Hermes Decision Trace

Sub2API 本地安装与 Hermes 接入验收报告

Sub2API 已完成 rootless 本地安装，三项用户态服务均 active/running，并已作为 Hermes custom:sub2api provider 接入。

🧭

推荐路径

继续保持 custom:sub2api 为可选 provider，不急着切默认模型；后续若要进 fallback 链，先补流式、tool_calls 和多工具 schema 验证。

🔎

关键依据

Sub2API /v1/models HTTP 200，gpt-5.5 真实 chat smoke 经由 AnyRouter adapter 返回 OK，Hermes config check 通过。

🛠️

落地方式

先把已验证方案当成稳定基线：保留当前 schedule / deliver / workdir，不急着继续扩面；新增候选先读源码、看 output、做 run-now 验证，再决定是否转 script-only。

证据摘要

三项服务已运行： sub2api.service、sub2api-postgres.service、sub2api-redis.service 全部 active/running，端口 18080 / 15432 / 16379 均监听在 127.0.0.1。
上游已接通： hermes-local API key 已绑定到 anyrouter/openai group，上游账号 anyrouter-adapter 为 active 且 schedulable。
调用已验证： Sub2API /v1/models HTTP 200，gpt-5.5 chat smoke 经由 AnyRouter adapter 返回 OK。

行动清单

保留当前 custom:sub2api 配置和独立 PostgreSQL/Redis 服务；如需启用为主路由或 fallback，再做工具调用与流式边界验收。

边界 / 风险

模型负载边界

Sub2API 后台账号测试接口默认测 gpt-5.4，该模型曾因上游负载达到上限报错；这不代表主链路失败。

访问范围边界

当前已验证主链路以 gpt-5.5 正常返回 HTTP 200；服务全部绑定 127.0.0.1，若未来外部访问需另做认证和反代设计。

完整记录

本节目录1. 总结结论 2. 安装与目录 3. systemd user 服务状态 4. 端口与绑定 5. Sub2API 初始化状态 6. Sub2API 数据配置 7. Hermes provider 接入情况 8. 模型目录验证 9. 真正调用验证 10. 延迟对比 11. 备份与回滚点 12. 当前推荐

Sub2API 本地安装与 Hermes 接入验收报告

1. 总结结论

Sub2API 已安装并运行：http://127.0.0.1:18080
部署方式：rootless 用户态安装，systemd --user 托管
数据依赖：独立 PostgreSQL + 独立 Redis，不复用 Hindsight 生产 PostgreSQL 5432
公网暴露：无；全部绑定 127.0.0.1
Hermes provider 名称：custom:sub2api
Sub2API 上游：AnyRouter adapter，走本机 http://127.0.0.1:8331
真实调用验证：POST /v1/chat/completions 使用 gpt-5.5 返回 OK，HTTP 200
当前默认 Hermes 主模型未切换：仍是 custom:jun / gpt-5.5；Sub2API 作为新增 provider 存在

2. 安装与目录

项	值
Sub2API 版本	`v0.1.133`
安装根目录	`/home/ht/apps/sub2api`
二进制	`/home/ht/apps/sub2api/bin/sub2api`
配置文件	`/home/ht/apps/sub2api/config.yaml`
Sub2API 本地 secret	`/home/ht/apps/sub2api/secrets.env`
Hermes provider key 文件	`/home/ht/apps/sub2api/hermes-provider.env`
Redis 安装目录	`/home/ht/apps/redis-local`
PostgreSQL 数据目录	`/home/ht/apps/sub2api/postgres-data`

说明：没有执行官方 sudo install.sh。官方脚本默认会写 /opt、创建系统用户并绑定 0.0.0.0:8080，本次按本地自用目标改为 rootless、localhost-only。

3. systemd user 服务状态

服务	状态	PID	重启次数	Unit
`sub2api.service`	active/running	`1930963`	`0`	`/home/ht/.config/systemd/user/sub2api.service`
`sub2api-postgres.service`	active/running	`1928016`	`0`	`/home/ht/.config/systemd/user/sub2api-postgres.service`
`sub2api-redis.service`	active/running	`1928012`	`0`	`/home/ht/.config/systemd/user/sub2api-redis.service`

4. 端口与绑定

端口	服务	绑定	说明
`18080`	Sub2API	`127.0.0.1`	Web UI + OpenAI-compatible API
`15432`	PostgreSQL	`127.0.0.1`	Sub2API 专用 PG 实例
`16379`	Redis	`127.0.0.1`	Sub2API 专用 Redis
`8331`	AnyRouter adapter	`127.0.0.1`	作为 Sub2API 上游

5. Sub2API 初始化状态

安装向导状态：

{"code":0,"data":{"needs_setup":false,"step":"completed"}}

表示 setup wizard 已完成，当前不是未初始化状态。

6. Sub2API 数据配置

6.1 用户

id	email	role	balance	concurrency	status
1	`admin@local.test`	admin	`99.99278500`	5	active

余额最初为 0，/v1/models 返回过 INSUFFICIENT_BALANCE；后续已给本地 admin 加测试余额 100，验证后余额略有扣减。

6.2 Groups

id	name	platform	status	rate_multiplier
1	default	anthropic	active	1.0000
2	anyrouter	openai	active	1.0000

6.3 API Keys

id	name	group_id	status	quota	quota_used	last_used_at
1	hermes-local	2	active	0	0	2026-06-05 20:59:00 CST

hermes-local 已从初始 default group 切到 anyrouter/openai group，否则 OpenAI-compatible 上游不会被路由到。

6.4 上游账号

id	name	platform	type	status	schedulable	base_url	group
1	anyrouter-adapter	openai	apikey	active	true	`http://127.0.0.1:8331`	anyrouter / id=2

备注：Sub2API 中上游 base_url 存为 http://127.0.0.1:8331，不是 /v1 结尾，避免转发时拼成 /v1/v1。

7. Hermes provider 接入情况

Hermes 主配置中新增 provider：

- name: sub2api base_url: http://127.0.0.1:18080/v1 api_key: ${SUB2API_HERMES_API_KEY} api_mode: chat_completions model_catalog: api model: gpt-5.5

Hermes provider 名称：

custom:sub2api

Hermes .env 新增：

SUB2API_HERMES_API_KEY=***

已验证：

hermes config check: OK custom provider exists: sub2api old provider name sub2api-local: absent

当前 Hermes 默认模型未切换：

model.default = gpt-5.5 model.provider = custom:jun

因此 Sub2API 接入不会影响当前默认主路由。

8. 模型目录验证

通过 Sub2API /v1/models 读取到 AnyRouter/OpenAI-compatible 模型目录，HTTP 200。主要模型包括：

gpt-5.5
gpt-5.4
gpt-5.4-mini
gpt-5.3-codex
gpt-5.3-codex-spark
gpt-5.2
gpt-image-1
gpt-image-1.5
gpt-image-2

9. 真正调用验证

9.1 Sub2API → AnyRouter adapter → 上游

请求：

POST http://127.0.0.1:18080/v1/chat/completions model: gpt-5.5 message: 只回复 OK stream: false

结果：

HTTP 200 assistant: OK

返回 usage 示例：

{ "prompt_tokens": 9, "completion_tokens": 17, "total_tokens": 26, "completion_tokens_details": { "reasoning_tokens": 10 } }

9.2 Sub2API 后台账号测试的小边界

Sub2API 后台账号测试接口默认测 gpt-5.4，曾返回：

gpt-5.4 负载已经达到上限

这不代表主链路失败。实际按 gpt-5.5 调用 Sub2API 已 HTTP 200。

10. 延迟对比

测试 payload：

model: gpt-5.5 messages: 只回复 OK stream: false max_tokens: 16

10.1 顺序测试，各 5 次

路径	成功	平均	中位数	最小	最大
direct-anyrouter	5/5	8235 ms	8915 ms	5402 ms	9645 ms
via-sub2api	5/5	6849 ms	4860 ms	4445 ms	12471 ms

10.2 交替成对测试，6 组

路径	成功	平均	中位数	最小	最大
direct	6/6	9564 ms	8912 ms	3222 ms	19870 ms
sub2api	6/6	7149 ms	6793 ms	4235 ms	12562 ms

成对差值 Sub2API - Direct：

avg: -2415 ms median: -3045 ms diffs: [3833, -12249, -4861, -1229, 4979, -4960]

判断：当前样本下看不出 Sub2API 带来明显额外延迟。真实延迟主要由 AnyRouter/上游波动主导，本地 Sub2API 转发层的开销被秒级上游波动淹没。

11. 备份与回滚点

配置修改前已备份：

/home/ht/.hermes/config.yaml.bak-sub2api-20260605-202627 /home/ht/.hermes/.env.bak-sub2api-20260605-202627 /home/ht/.hermes/config.yaml.bak-rename-sub2api-20260605-203328

主要回滚动作：

cp /home/ht/.hermes/config.yaml.bak-rename-sub2api-20260605-203328 /home/ht/.hermes/config.yaml # 如需回滚 env： cp /home/ht/.hermes/.env.bak-sub2api-20260605-202627 /home/ht/.hermes/.env

服务停止：

systemctl --user stop sub2api.service sub2api-postgres.service sub2api-redis.service

服务启动：

systemctl --user start sub2api-postgres.service sub2api-redis.service sub2api.service

12. 当前推荐

保持 custom:sub2api 作为可选 provider，不急着切默认模型。
若后续要放进 Hermes fallback 链，建议先再做一次流式 stream=true、工具调用 tool_calls、多工具 schema 验证。
若只用于本地统一管理/观测，当前状态已经够用。

---

模型：gpt-5.5 · 生成时间：2026-06-05 20:59 CST · 归档类型：Sub2API local install & Hermes provider report

</footer>