oy-paddy
117 lines
3.3 KiB
Markdown
117 lines
3.3 KiB
Markdown
# 状态文件说明
|
|
|
|
本服务使用 JSON 文件保存模型冷却状态。这样服务重启后，已经进入冷却期的 DashScope key 与 `MODEL_ID` 组合不会丢失。
|
|
|
|
默认状态文件路径：
|
|
|
|
```env
|
|
STATE_PATH=./data/proxy-state.json
|
|
```
|
|
|
|
状态文件不会保存明文 DashScope API Key。代码会对每个 key 计算 SHA-256，并把结果写入 `modelState`。
|
|
|
|
## 文件结构
|
|
|
|
状态文件是一个版本化 JSON 对象：
|
|
|
|
```json
|
|
{
|
|
"version": 1,
|
|
"modelState": {},
|
|
"runtimeState": {}
|
|
}
|
|
```
|
|
|
|
## modelState
|
|
|
|
`modelState` 保存每个 DashScope key 与 `MODEL_ID` 组合的状态。
|
|
|
|
例如配置：
|
|
|
|
```env
|
|
DASHSCOPE_API_KEYS=key1,key2
|
|
MODEL_IDS=modelA,modelB,modelC
|
|
```
|
|
|
|
那么 `modelState` 会有 `2 * 3 = 6` 条记录。
|
|
|
|
字段说明：
|
|
|
|
| 字段 | 说明 |
|
|
| --- | --- |
|
|
| `keyHash` | DashScope API Key 的 SHA-256 hash。用于区分不同 key，但不保存明文 key。 |
|
|
| `modelId` | 模型 ID，来自 `MODEL_IDS`。 |
|
|
| `cooldownUntil` | 冷却截止时间，Unix 毫秒时间戳。`0` 表示没有冷却。如果这个值大于当前时间，该 key+model 组合不可用。 |
|
|
| `failureCount` | 该 key+model 组合触发免费额度耗尽 403 的次数。 |
|
|
| `lastError` | 最近一次免费额度耗尽时，上游返回的错误信息。 |
|
|
| `lastUsedAt` | 最近一次成功使用该 key+model 组合的时间，Unix 毫秒时间戳。 |
|
|
| `updatedAt` | 最近一次状态更新时间，Unix 毫秒时间戳。 |
|
|
|
|
## runtimeState
|
|
|
|
`runtimeState` 保存调度游标，避免服务每次重启后都从第一个 key、第一条 model 开始打。
|
|
|
|
当前会使用的记录：
|
|
|
|
| `name` | 说明 |
|
|
| --- | --- |
|
|
| `key_cursor` | 当前优先使用的 DashScope API Key 下标。 |
|
|
| `model_cursor:<key_hash>` | 某个 key 当前优先使用的模型下标。 |
|
|
|
|
每条记录包含：
|
|
|
|
| 字段 | 说明 |
|
|
| --- | --- |
|
|
| `value` | 状态值。当前主要保存数字游标，但统一用文本存储。 |
|
|
| `updatedAt` | 最近一次更新时间，Unix 毫秒时间戳。 |
|
|
|
|
## 写入策略
|
|
|
|
状态变更会同步写入文件。写入时先写临时文件，再用 `rename` 替换正式状态文件，降低进程中断时写坏文件的风险。
|
|
|
|
如果启动时发现状态文件不是有效 JSON，或结构不符合当前版本，服务会把原文件重命名为：
|
|
|
|
```text
|
|
proxy-state.json.bak.<timestamp>
|
|
```
|
|
|
|
然后创建新的空状态。
|
|
|
|
## 调度规则
|
|
|
|
当前实现是“key 优先”的切换策略：
|
|
|
|
1. 先使用 `key_cursor` 指向的 key。
|
|
2. 在这个 key 内部，从该 key 的 `model_cursor` 指向的模型开始尝试。
|
|
3. 如果某个模型返回免费额度耗尽 403，只冷却这个 `keyHash + modelId` 组合。
|
|
4. 继续尝试同一个 key 下的下一个可用模型。
|
|
5. 只有当前 key 下所有模型都不可用时，才切换到下一个 key。
|
|
6. 如果所有 key+model 组合都不可用，服务返回 `503`。
|
|
|
|
## 冷却规则
|
|
|
|
默认冷却时间是 1 个月：
|
|
|
|
```env
|
|
MODEL_COOLDOWN_SECONDS=2592000
|
|
```
|
|
|
|
当某个 key+model 组合进入冷却：
|
|
|
|
```text
|
|
cooldownUntil = 当前时间 + MODEL_COOLDOWN_SECONDS
|
|
failureCount = failureCount + 1
|
|
lastError = 上游错误信息
|
|
updatedAt = 当前时间
|
|
```
|
|
|
|
当某个 key+model 组合成功返回：
|
|
|
|
```text
|
|
lastUsedAt = 当前时间
|
|
lastError = null
|
|
updatedAt = 当前时间
|
|
```
|
|
|
|
成功返回不会清零 `failureCount`，这个字段保留历史失败次数。
|