auto-model-key-router 1.1.1__tar.gz

auto_model_key_router-1.1.1/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: auto-model-key-router
+Version: 1.1.1
+Summary: A lightweight local OpenAI-compatible model API key router
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: tzdata>=2025.2; platform_system == "Windows"
+Requires-Dist: uvicorn>=0.30.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Provides-Extra: release
+Requires-Dist: build>=1.2.0; extra == "release"
+Requires-Dist: twine>=5.0.0; extra == "release"
+
+Auto Model Key Router 是一个轻量的本地 API key 路由服务。它支持为同一个模型 ID 配置多个 API key，并以轮询/优先级的方式把请求自动分配到可用 key；当上游返回认证、限流或服务错误时，会依次切换到已配置的其他 key，只有单 key 配置才会按重试次数重复尝试同一个 key。
+
+## 功能
+
+- 支持 OpenAI-compatible `/v1/*` 请求转发
+- 支持同一模型 ID 配置多个 key
+- 支持按模型维度选择“分流”或“优先级”路由模式
+- 支持 key 失败后自动尝试下一个 key
+- 支持请求量、成功/失败、重试、状态码、Token 使用量和缓存命中统计
+- 支持 Rich CLI 展示配置摘要、交互式添加配置和日志板块
+- 支持 `/health`、`/metrics` 和 `/v1/models` 本地接口
+
+## 安装
+
+```bash
+pip install -e .
+```
+
+## 配置
+
+首次运行时，如果 `router-config.json` 不存在，程序会自动生成一个空配置文件。你也可以复制示例配置：
+
+```bash
+copy router-config.example.json router-config.json
+```
+
+编辑 `router-config.json`：
+
+```json
+{
+  "host": "127.0.0.1",
+  "port": 8000,
+  "default_base_url": "https://api.openai.com",
+  "request_timeout": 60,
+  "max_retries": 2,
+  "metrics_db_path": "",
+  "log_file_path": "",
+  "local_api_key": "amkr-generated-local-api-key",
+  "models": [
+    {
+      "id": "gpt-4o-mini",
+      "aliases": ["gpt-4o-mini-display", "fast-mini"],
+      "routing_mode": "round_robin",
+      "keys": [
+        { "name": "key-1", "api_key": "sk-your-first-key" },
+        { "name": "key-2", "api_key": "sk-your-second-key" }
+      ]
+    }
+  ]
+}
+```
+
+也可以为某个 key 单独配置 `base_url`，用于接入其他 OpenAI-compatible 上游。
+
+每个模型配置中的 `id` 是统一路由用的真实模型 ID；`aliases` 是额外显示名称或别名。客户端请求中使用 `id` 或任意 `aliases` 都会映射到同一个模型配置和同一组 key。
+
+`routing_mode` 支持两种模式：
+
+- `round_robin`：分流模式，按配置顺序轮询多个 key，把请求均匀分配到不同 key，这是默认模式。
+- `priority`：优先级模式，每次请求优先使用配置中排在最前面的 key；只有当前 key 请求失败且状态码可重试，才会按顺序尝试后面的 key。
+
+默认配置文件也会保存在同一个系统应用缓存目录中，文件名为 `router-config.json`。如果当前目录存在旧的 `router-config.json`，首次未指定 `--config` 启动时会自动复制到默认缓存目录。
+
+`metrics_db_path` 和 `log_file_path` 为空时会使用系统默认应用缓存目录：
+
+- Windows：`%LOCALAPPDATA%\\AutoModelKeyRouter\\`
+- macOS：`~/Library/Caches/AutoModelKeyRouter/`
+- Linux：`${XDG_CACHE_HOME:-~/.cache}/auto-model-key-router/`
+
+默认文件名为：
+
+- 配置文件：`router-config.json`
+- SQLite 计量存档：`metrics.sqlite3`
+- 服务运行日志：`server.log`
+- 后台服务 PID：`server.pid`，与日志文件同目录
+
+如果需要，也可以把 `metrics_db_path` 和 `log_file_path` 配成绝对路径。
+
+## 运行
+
+启动默认进入 Terminal UI：
+
+```bash
+amkr --config router-config.json
+```
+
+也可以使用完整命令名：
+
+```bash
+auto-model-key-router --config router-config.json
+```
+
+主菜单包含：
+
+- 管理系统服务 / 开机自启动
+- 交互式添加模型 / API key
+- 生成 / 重置本地 API key
+- 配置监听地址与端口
+- 查看日志板块
+- 退出
+
+Terminal UI 只负责配置与服务管理，不直接承载一次性的启动逻辑。需要直接启动本地服务时使用命令行入口：
+
+```bash
+auto-model-key-router --config router-config.json --serve
+```
+
+查看后台服务状态：
+
+```bash
+auto-model-key-router --config router-config.json --status
+```
+
+停止后台服务：
+
+```bash
+auto-model-key-router --config router-config.json --stop
+```
+
+后台服务会写入 PID 文件，默认与运行日志同目录，例如系统缓存目录下的 `server.pid`。
+
+注册为系统服务并启用开机自启动：
+
+```bash
+auto-model-key-router --config router-config.json --install-service
+```
+
+Windows 下会注册为用户登录时启动的计划任务 `AutoModelKeyRouter` 并立即启动。Linux 下会注册为 systemd user service：`auto-model-key-router.service` 并立即启动，同时尝试启用 linger 以支持用户未登录时启动。
+
+也可以使用统一服务管理命令：
+
+```bash
+auto-model-key-router --config router-config.json --service install
+auto-model-key-router --config router-config.json --service status
+auto-model-key-router --config router-config.json --service start
+auto-model-key-router --config router-config.json --service stop
+auto-model-key-router --config router-config.json --service restart
+auto-model-key-router --config router-config.json --service uninstall
+```
+
+Terminal UI 中的“管理系统服务 / 开机自启动”会进入服务管理子菜单，可直接安装、卸载、启动、停止、重启和查看状态。
+
+只查看配置摘要：
+
+```bash
+auto-model-key-router --config router-config.json --show-config
+```
+
+覆盖监听地址：
+
+```bash
+auto-model-key-router --config router-config.json --host 0.0.0.0 --port 8000
+```
+
+也可以在 Terminal UI 中配置监听地址。默认只监听 `127.0.0.1`，配置为 `0.0.0.0` 时会接受所有可达网络的连接；如果机器暴露在公网或未受信任网络中，请务必启用本地鉴权、限制防火墙访问，并避免泄露上游 API Key。Terminal UI 首页会在检测到 `0.0.0.0` 时显示显眼风险提示。
+
+如果配置文件没有模型，直接启动服务时会自动进入交互式配置，依次输入模型 ID、Key 名称、上游 `base_url` 和 API key。
+
+也可以通过命令直接查看日志板块，默认显示最近 20 行运行日志和最近 20 条请求记录：
+
+```bash
+auto-model-key-router --config router-config.json --show-logs
+```
+
+指定日志行数和请求记录条数：
+
+```bash
+auto-model-key-router --config router-config.json --show-logs 50
+```
+
+## 请求示例
+
+```bash
+curl http://127.0.0.1:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your-local-api-key" \
+  -d "{\"model\":\"gpt-4o-mini\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}"
+```
+
+本地服务会根据请求体中的 `model` 字段选择对应 key，并把请求转发到该 key 配置的上游 `/v1/chat/completions`。
+
+也兼容 Anthropic Messages 和 OpenAI Responses 风格的消息输入：
+
+- 请求 `/v1/messages` 时会把 Anthropic 顶层 `system` 转为 system message，并把 `content` 中的 `text`、base64 `image` 块转为 OpenAI-compatible 消息块后转发到上游 `/v1/chat/completions`。
+- 请求 `/v1/responses` 时会把 `instructions` 转为 system message，把 `input` 字符串或消息数组转为 `messages` 后转发到上游 `/v1/chat/completions`。
+- 请求 `/v1/chat/completions` 时也会兼容 Anthropic 风格的顶层 `system` 和 Responses 风格的 content part 类型。
+
+## 本地鉴权
+
+首次生成配置文件时会自动生成 `local_api_key`。如果旧配置中该字段为空，程序加载配置时也会自动补齐。也可以在 Terminal UI 中选择“生成 / 重置本地 API key”重新生成。
+
+设置后，客户端访问本地 `/v1/*` 接口时需要传入：
+
+```bash
+Authorization: Bearer your-local-api-key
+```
+
+也支持使用：
+
+```bash
+x-api-key: your-local-api-key
+```
+
+如果 `local_api_key` 为空，则不启用本地鉴权。
+
+## 计量统计
+
+服务会把计量数据写入 SQLite 存档。`metrics_db_path` 为空时默认写入系统应用缓存目录下的 `metrics.sqlite3`，也可以通过配置项 `metrics_db_path` 修改存档路径，并通过 `/metrics` 查看聚合统计：
+
+```bash
+curl http://127.0.0.1:8000/metrics
+```
+
+返回数据包含：
+
+- `total`：全局累计统计
+- `models`：按真实模型 ID 汇总的统计
+- `requested_models`：按客户端请求使用的模型名/别名汇总的统计
+- `model_requested_models`：在真实模型 ID 下按请求模型名/别名拆分的统计
+- `keys`：按真实模型 ID 和 key 名称拆分的统计
+- `requests`：实际尝试上游 key 的次数
+- `successes` / `failures`：成功与失败次数
+- `retries`：因上游错误或请求异常触发切换 key 的次数
+- `prompt_tokens` / `completion_tokens` / `total_tokens`：从上游响应 `usage` 字段提取的 Token 用量
+- `cached_tokens`：OpenAI-compatible `prompt_tokens_details.cached_tokens` 或顶层 `cached_tokens` 的缓存 Token 数
+- `cache_creation_input_tokens` / `cache_read_input_tokens`：Anthropic-compatible 缓存写入与读取 Token 数
+- `cache_hits` / `cache_misses` / `cache_hit_rate`：按请求维度统计缓存命中、未命中和命中率
+- `cached_token_rate`：缓存 Token 占输入 Token 的比例
+- `total_duration_ms` / `avg_duration_ms` / `min_duration_ms` / `max_duration_ms`：上游响应耗时统计，单位毫秒
+- `status_codes`：上游响应状态码分布
+- `database_path`：当前 SQLite 存档路径
+
+统计记录会持久化保存，服务重启后 `/metrics` 会继续基于同一个 SQLite 文件聚合历史数据。

auto_model_key_router-1.1.1/README.md

@@ -0,0 +1,233 @@
+Auto Model Key Router 是一个轻量的本地 API key 路由服务。它支持为同一个模型 ID 配置多个 API key，并以轮询/优先级的方式把请求自动分配到可用 key；当上游返回认证、限流或服务错误时，会依次切换到已配置的其他 key，只有单 key 配置才会按重试次数重复尝试同一个 key。
+
+## 功能
+
+- 支持 OpenAI-compatible `/v1/*` 请求转发
+- 支持同一模型 ID 配置多个 key
+- 支持按模型维度选择“分流”或“优先级”路由模式
+- 支持 key 失败后自动尝试下一个 key
+- 支持请求量、成功/失败、重试、状态码、Token 使用量和缓存命中统计
+- 支持 Rich CLI 展示配置摘要、交互式添加配置和日志板块
+- 支持 `/health`、`/metrics` 和 `/v1/models` 本地接口
+
+## 安装
+
+```bash
+pip install -e .
+```
+
+## 配置
+
+首次运行时，如果 `router-config.json` 不存在，程序会自动生成一个空配置文件。你也可以复制示例配置：
+
+```bash
+copy router-config.example.json router-config.json
+```
+
+编辑 `router-config.json`：
+
+```json
+{
+  "host": "127.0.0.1",
+  "port": 8000,
+  "default_base_url": "https://api.openai.com",
+  "request_timeout": 60,
+  "max_retries": 2,
+  "metrics_db_path": "",
+  "log_file_path": "",
+  "local_api_key": "amkr-generated-local-api-key",
+  "models": [
+    {
+      "id": "gpt-4o-mini",
+      "aliases": ["gpt-4o-mini-display", "fast-mini"],
+      "routing_mode": "round_robin",
+      "keys": [
+        { "name": "key-1", "api_key": "sk-your-first-key" },
+        { "name": "key-2", "api_key": "sk-your-second-key" }
+      ]
+    }
+  ]
+}
+```
+
+也可以为某个 key 单独配置 `base_url`，用于接入其他 OpenAI-compatible 上游。
+
+每个模型配置中的 `id` 是统一路由用的真实模型 ID；`aliases` 是额外显示名称或别名。客户端请求中使用 `id` 或任意 `aliases` 都会映射到同一个模型配置和同一组 key。
+
+`routing_mode` 支持两种模式：
+
+- `round_robin`：分流模式，按配置顺序轮询多个 key，把请求均匀分配到不同 key，这是默认模式。
+- `priority`：优先级模式，每次请求优先使用配置中排在最前面的 key；只有当前 key 请求失败且状态码可重试，才会按顺序尝试后面的 key。
+
+默认配置文件也会保存在同一个系统应用缓存目录中，文件名为 `router-config.json`。如果当前目录存在旧的 `router-config.json`，首次未指定 `--config` 启动时会自动复制到默认缓存目录。
+
+`metrics_db_path` 和 `log_file_path` 为空时会使用系统默认应用缓存目录：
+
+- Windows：`%LOCALAPPDATA%\\AutoModelKeyRouter\\`
+- macOS：`~/Library/Caches/AutoModelKeyRouter/`
+- Linux：`${XDG_CACHE_HOME:-~/.cache}/auto-model-key-router/`
+
+默认文件名为：
+
+- 配置文件：`router-config.json`
+- SQLite 计量存档：`metrics.sqlite3`
+- 服务运行日志：`server.log`
+- 后台服务 PID：`server.pid`，与日志文件同目录
+
+如果需要，也可以把 `metrics_db_path` 和 `log_file_path` 配成绝对路径。
+
+## 运行
+
+启动默认进入 Terminal UI：
+
+```bash
+amkr --config router-config.json
+```
+
+也可以使用完整命令名：
+
+```bash
+auto-model-key-router --config router-config.json
+```
+
+主菜单包含：
+
+- 管理系统服务 / 开机自启动
+- 交互式添加模型 / API key
+- 生成 / 重置本地 API key
+- 配置监听地址与端口
+- 查看日志板块
+- 退出
+
+Terminal UI 只负责配置与服务管理，不直接承载一次性的启动逻辑。需要直接启动本地服务时使用命令行入口：
+
+```bash
+auto-model-key-router --config router-config.json --serve
+```
+
+查看后台服务状态：
+
+```bash
+auto-model-key-router --config router-config.json --status
+```
+
+停止后台服务：
+
+```bash
+auto-model-key-router --config router-config.json --stop
+```
+
+后台服务会写入 PID 文件，默认与运行日志同目录，例如系统缓存目录下的 `server.pid`。
+
+注册为系统服务并启用开机自启动：
+
+```bash
+auto-model-key-router --config router-config.json --install-service
+```
+
+Windows 下会注册为用户登录时启动的计划任务 `AutoModelKeyRouter` 并立即启动。Linux 下会注册为 systemd user service：`auto-model-key-router.service` 并立即启动，同时尝试启用 linger 以支持用户未登录时启动。
+
+也可以使用统一服务管理命令：
+
+```bash
+auto-model-key-router --config router-config.json --service install
+auto-model-key-router --config router-config.json --service status
+auto-model-key-router --config router-config.json --service start
+auto-model-key-router --config router-config.json --service stop
+auto-model-key-router --config router-config.json --service restart
+auto-model-key-router --config router-config.json --service uninstall
+```
+
+Terminal UI 中的“管理系统服务 / 开机自启动”会进入服务管理子菜单，可直接安装、卸载、启动、停止、重启和查看状态。
+
+只查看配置摘要：
+
+```bash
+auto-model-key-router --config router-config.json --show-config
+```
+
+覆盖监听地址：
+
+```bash
+auto-model-key-router --config router-config.json --host 0.0.0.0 --port 8000
+```
+
+也可以在 Terminal UI 中配置监听地址。默认只监听 `127.0.0.1`，配置为 `0.0.0.0` 时会接受所有可达网络的连接；如果机器暴露在公网或未受信任网络中，请务必启用本地鉴权、限制防火墙访问，并避免泄露上游 API Key。Terminal UI 首页会在检测到 `0.0.0.0` 时显示显眼风险提示。
+
+如果配置文件没有模型，直接启动服务时会自动进入交互式配置，依次输入模型 ID、Key 名称、上游 `base_url` 和 API key。
+
+也可以通过命令直接查看日志板块，默认显示最近 20 行运行日志和最近 20 条请求记录：
+
+```bash
+auto-model-key-router --config router-config.json --show-logs
+```
+
+指定日志行数和请求记录条数：
+
+```bash
+auto-model-key-router --config router-config.json --show-logs 50
+```
+
+## 请求示例
+
+```bash
+curl http://127.0.0.1:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your-local-api-key" \
+  -d "{\"model\":\"gpt-4o-mini\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}"
+```
+
+本地服务会根据请求体中的 `model` 字段选择对应 key，并把请求转发到该 key 配置的上游 `/v1/chat/completions`。
+
+也兼容 Anthropic Messages 和 OpenAI Responses 风格的消息输入：
+
+- 请求 `/v1/messages` 时会把 Anthropic 顶层 `system` 转为 system message，并把 `content` 中的 `text`、base64 `image` 块转为 OpenAI-compatible 消息块后转发到上游 `/v1/chat/completions`。
+- 请求 `/v1/responses` 时会把 `instructions` 转为 system message，把 `input` 字符串或消息数组转为 `messages` 后转发到上游 `/v1/chat/completions`。
+- 请求 `/v1/chat/completions` 时也会兼容 Anthropic 风格的顶层 `system` 和 Responses 风格的 content part 类型。
+
+## 本地鉴权
+
+首次生成配置文件时会自动生成 `local_api_key`。如果旧配置中该字段为空，程序加载配置时也会自动补齐。也可以在 Terminal UI 中选择“生成 / 重置本地 API key”重新生成。
+
+设置后，客户端访问本地 `/v1/*` 接口时需要传入：
+
+```bash
+Authorization: Bearer your-local-api-key
+```
+
+也支持使用：
+
+```bash
+x-api-key: your-local-api-key
+```
+
+如果 `local_api_key` 为空，则不启用本地鉴权。
+
+## 计量统计
+
+服务会把计量数据写入 SQLite 存档。`metrics_db_path` 为空时默认写入系统应用缓存目录下的 `metrics.sqlite3`，也可以通过配置项 `metrics_db_path` 修改存档路径，并通过 `/metrics` 查看聚合统计：
+
+```bash
+curl http://127.0.0.1:8000/metrics
+```
+
+返回数据包含：
+
+- `total`：全局累计统计
+- `models`：按真实模型 ID 汇总的统计
+- `requested_models`：按客户端请求使用的模型名/别名汇总的统计
+- `model_requested_models`：在真实模型 ID 下按请求模型名/别名拆分的统计
+- `keys`：按真实模型 ID 和 key 名称拆分的统计
+- `requests`：实际尝试上游 key 的次数
+- `successes` / `failures`：成功与失败次数
+- `retries`：因上游错误或请求异常触发切换 key 的次数
+- `prompt_tokens` / `completion_tokens` / `total_tokens`：从上游响应 `usage` 字段提取的 Token 用量
+- `cached_tokens`：OpenAI-compatible `prompt_tokens_details.cached_tokens` 或顶层 `cached_tokens` 的缓存 Token 数
+- `cache_creation_input_tokens` / `cache_read_input_tokens`：Anthropic-compatible 缓存写入与读取 Token 数
+- `cache_hits` / `cache_misses` / `cache_hit_rate`：按请求维度统计缓存命中、未命中和命中率
+- `cached_token_rate`：缓存 Token 占输入 Token 的比例
+- `total_duration_ms` / `avg_duration_ms` / `min_duration_ms` / `max_duration_ms`：上游响应耗时统计，单位毫秒
+- `status_codes`：上游响应状态码分布
+- `database_path`：当前 SQLite 存档路径
+
+统计记录会持久化保存，服务重启后 `/metrics` 会继续基于同一个 SQLite 文件聚合历史数据。

auto_model_key_router-1.1.1/auto_model_key_router/__init__.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+
+pyproject = Path(__file__).resolve().parents[1] / "pyproject.toml"
+if pyproject.exists():
+    import tomllib
+
+    __version__ = tomllib.loads(pyproject.read_text(encoding="utf-8"))["project"]["version"]
+else:
+    try:
+        __version__ = version("auto-model-key-router")
+    except PackageNotFoundError:
+        __version__ = "0.0.0"