{"repo": "chatgpt34993/llm-key-pool", "files": {"README.md": {"768d3f99e58ddd9b74d69458840fca69d2d5ee7b": {"t": 1785674114.6721854, "n": 4055, "h": "2c0704e18bd707d1", "c": "# LLM Key Pool\n\n分层轮询多平台 LLM API Key 管理工具，支持故障转移与自动切换。\n\n## 兼容运行平台\n\n本工具/skill 可安装运行于以下AI编程客户端：\n\n| 平台 | 安装方式 | 支持 |\n|------|---------|------|\n| **Claude Code** | Skill 直接安装 | ✅ 原生支持 |\n| **OpenClaw** | 作为Python依赖库集成 | ✅ 原生支持 |\n| **OpenCode** | 作为Python依赖库集成 | ✅ 原生支持 |\n| **通义千问 (Qwen)** | 命令行调用 / Python集成 | ✅ 支持 |\n| **Any editor/IDE** | Python脚本调用 | ✅ 支持 |\n| **独立使用** | 命令行直接调用 | ✅ 支持 |\n\n## 功能\n\n- **三层 Key 池**：主力层 (primary) → 每日回血层 (daily) → 兜底层 (fallback)\n- **智能故障转移**：429 自动冷却、401 永久禁用、500/503 重试\n- **OpenAI 兼容接口**：统一 `/chat/completions` 格式，同时支持 Anthropic Messages API\n- **多平台支持**：主流大模型厂商全兼容（见下方完整列表）\n- **线程安全**：内置锁机制，支持并发调用\n\n## 支持的AI模型平台\n\n所有支持OpenAI兼容接口的大模型平台均可接入，当前已验证支持：\n\n### 主力层 (primary) - 高额度推荐\n- **阿里云百炼** - qwen-max, qwen-plus, qwen-turbo\n- **智谱AI** - glm-4, glm-3-turbo, glm-4-air\n- **小龙虾** - xiaolongxia-72b, xiaolongxia-34b\n\n### 每日回血层 (daily) - 额度每日刷新\n- **火山引擎** - doubao-pro-256k, doubao-pro-32k\n- **Google AI Studio** - gemini-1.5-pro, gemini-1.5-flash\n\n### 兜底层 (fallback) - 开源/聚合平台保证可用性\n- **硅基流动** - Qwen2.5, Llama 3.1, GLM-4 等开源模型\n- **OpenRouter** - 聚合上百种大模型，免费模型可用\n- **GitHub Models** - GitHub官方模型服务\n- **Groq** - 极速推理，免费额度\n- **OpenCode** - 专注代码生成\n- **Qwen独立API** - 通义千问独立API服务\n- **ClaudeCode (Anthropic)** - claude-3-5-sonnet, claude-3-opus\n- **腾讯混元** - hunyuan-lite, hunyuan-standard\n\n> 详细配置说明见：[references/supported_providers.md](references/supported_providers.md)\n\n## 安装\n\n### 方式一：作为 Claude Code Skill 安装（推荐）\n\nClaude Code 用户可以安装为 Skill：\n\n```bash\n# 创建 skills 目录（如果不存在）\nmkdir -p ~/.claude/skills\n\n# 克隆或复制项目到 skills 目录\ngit clone https://github.com/OpenClaw/llm-key-pool.git ~/.claude/skills/llm-key-pool\n\n# 安装依赖\npip install -r ~/.claude/skills/llm-key-pool/requirements.txt\n```\n\nWindows 路径：\n```\nC:\\Users\\用户名\\.claude\\skills\\llm-key-pool\\\n```\n\n安装后，Claude Code 需要调用大模型时会自动触发该 Skill。\n\n### 方式二：作为独立 Python 包安装\n\n```bash\npip install .\n```\n\n或可编辑模式（开发）：\n\n```bash\npip install -e .\n```\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\npip install -r requirements.txt\n# 或者如果已经 pip 安装了包，可以跳过这一步\n```\n\n### 2. 创建配置文件（填入你的 API Key）\n\n项目中已经提供了配置模板，只需要复制并填写你的 API Key：\n\n```bash\n# 复制模板文件到当前目录\ncp assets/llm_config.yaml.example ./llm_config.yaml\n\n# 编辑文件，替换占位符为你的真实 API Key\nnotepad llm_config.yaml  # Windows\n# 或者\nvim llm_config.yaml     # Linux/macOS\n```\n\n**模板位置**: `assets/llm_config.yaml.example` 已经预填了各大平台的配置，你只需要：\n- 去掉不需要平台的注释（或保留，删掉占位符 `sk-...` 换成你的 Key）\n- 将 `\"sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"` 替换成你真实的 API Key\n- `.gitignore` 已经默认忽略 `llm_config.yaml`，不用担心密钥泄露\n\n### 3. 调用 LLM\n\n```bash\npython -m llm_key_pool.llm_client \\\n  --config ./llm_config.yaml \\\n  --prompt \"你好，请介绍一下自己\"\n```\n\n### 4. 在 Python 代码中使用\n\n```python\nfrom llm_key_pool import TieredLLMClient\n\nclient = TieredLLMClient('./llm_config.yaml')\nresult, usage_info = client.call_llm(prompt=\"你好\")\nprint(result)\n```\n\n## 分层架构\n\n| 层级 | 说明 | 推荐平台 |\n|------|------|---------|\n| `primary` | 主力层，高额度 | 阿里云百炼、智谱 AI |\n| `daily` | 每日回血层，额度每日刷新 | 火山引擎、Google AI Studio |\n| `fallback` | 兜底层，开源/聚合平台 | 硅基流动、OpenRouter、Groq |\n\n系统自动从主力层开始轮询，不可用时自动切换到下一层，无需手动干预。\n\n## 命令行参数\n\n| 参数 | 说明 |\n|------|------|\n| `--config` | 配置文件路径（默认：`./llm_config.yaml`） |\n| `--prompt` | 用户提示词 |\n| `--system-prompt` | 系统提示词（可选） |\n| `--temperature` | 温度参数（默认：0.7） |\n| `--max-tokens` | 最大 Token 数（默认：2000） |\n| `--test` | 测试配置 |\n| `--status` | 查看 Key 池状态 |\n\n## 配置示例\n\n```yaml\nproviders:\n  alibaba_bailian:\n    tier: primary\n    model: \"qwen-max\"\n    api_keys:\n      - \"sk-your-api-key\"\n    base_url: \"https://dashscope.aliyuncs.com/compatible-mode/v1\"\n\n  siliconflow:\n    tier: fallback\n    model: \"Qwen/Qwen2.5-7B-Instruct\"\n    api_keys:\n      - \"sk-your-api-key\"\n    base_url: \"https://api.siliconflow.cn/v1\"\n\nglobal:\n  max_retries: 3\n  cooldown_seconds: 300\n  error_threshold: 5\n```\n\n## 项目结构\n\n```\nllm-key-pool/\n├── llm_key_pool/            # 核心包\n│   ├── __init__.py\n│   ├── config_loader.py     # 配置加载与验证\n│   ├── key_pool.py          # Key 池管理与轮询\n│   └── llm_client.py        # LLM 调用客户端\n├── assets/                  # 模板与示例\n├── references/              # 参考文档\n├── pyproject.toml\n├── requirements.txt\n├── LICENSE\n└── README.md\n```\n\n## 许可证\n\nApache License 2.0\n"}}}}