Loading... # Octopus LLM API 聚合服务技术分析 # 一、概述 ## 1. 项目简介 Octopus 是一个面向个人的 LLM API 聚合与负载均衡服务，旨在为用户提供统一接入多个大语言模型提供商的能力。项目采用 Go 语言后端结合 Next.js 前端的架构设计，提供简洁优雅的 Web 管理界面。 ## 2. 核心价值 ### A. 统一接入 通过单一服务接入 OpenAI、Anthropic、Gemini 等多个 LLM 提供商，简化多模型调用流程。 ### B. 成本优化 支持多 API Key 轮询使用，智能选择最低延迟的端点，帮助用户优化使用成本和响应速度。 ### C. 协议兼容 实现 OpenAI Chat、OpenAI Responses、Anthropic API 等多种协议的无缝转换，降低客户端集成复杂度。 # 二、系统架构 ## 1. 技术栈 ```mermaid graph TB Client[客户端] --> API[Octopus API] API --> LB[负载均衡层] LB --> Channel1[OpenAI 通道] LB --> Channel2[Anthropic 通道] LB --> Channel3[Gemini 通道] Channel1 --> Provider1[提供商1] Channel1 --> Provider2[提供商2] Channel2 --> Provider3[提供商3] Channel3 --> Provider4[提供商4] API --> DB[(数据库)] API --> Cache[内存缓存] Cache --> DB Web[Web管理面板] --> API ```   ## 2. 组件说明 ### A. 后端服务（Go） - 提供统一的 API 接口 - 实现负载均衡和协议转换 - 处理通道管理和请求路由 - 统计数据收集与存储 ### B. 前端管理界面（Next.js） - 通道配置与管理 - 模型分组与负载均衡策略设置 - 价格管理与统计数据展示 - 系统配置与监控 ### C. 数据存储 - 支持 SQLite、MySQL、PostgreSQL - 存储通道配置、模型信息、统计数据 - 自动创建表结构 # 三、核心功能 ## 1. 通道管理 通道是连接 LLM 提供商的基本配置单元。 ### A. 多通道聚合 支持同时配置多个 LLM 提供商的通道，每个通道包含： - 基础 URL - 多个 API Key - 多个端点地址 ### B. 智能端点选择 每个通道支持配置多个端点，系统自动选择延迟最短的端点进行请求。 ### C. 协议类型支持 | 协议类型 | 自动追加路径 | 应用场景 | |---------|-------------|---------| | OpenAI Chat | /chat/completions | 对话补全 | | OpenAI Responses | /responses | 结构化响应 | | Anthropic | /messages | Claude 模型 | | Gemini | /models/:model:generateContent | Gemini 模型 | **★ Insight ─────────────────────────────────────** 1. **自动路径拼接设计**：用户只需提供基础 URL，系统根据通道类型自动追加 API 路径，这种设计降低了配置复杂度，减少了用户错误。 2. **多端点智能选择**：通过实时监测各端点延迟，自动选择最优路径，这种动态优化机制能有效提升用户体验。 `─────────────────────────────────────────────────` ## 2. 分组管理与负载均衡 分组将多个通道聚合为一个统一的外部模型名称。 ### A. 负载均衡模式 ```mermaid graph LR Request[请求] --> Router{负载均衡器} Router -->|轮询| CH1[通道1] Router -->|随机| CH2[通道2] Router -->|故障转移| CH3[通道3] Router -->|加权| CH4[通道4] CH1 --> Provider1[提供商1] CH2 --> Provider2[提供商2] CH3 --> Provider3[提供商3] CH4 --> Provider4[提供商4] ```   ### B. 模式详解 | 模式 | 描述 | 适用场景 | |------|------|---------| | 轮询 | 按顺序依次使用各通道 | 通道能力相近，需要均匀分配请求 | | 随机 | 随机选择可用通道 | 通道能力相近，不需要严格顺序 | | 故障转移 | 优先使用高优先级通道，失败时切换 | 有主备通道之分，需要高可用性 | | 加权 | 按配置权重分配请求 | 通道能力不同，需要按比例分配 | **★ Insight ─────────────────────────────────────** 1. **故障转移机制**：高优先级通道优先使用，失败时自动降级到低优先级通道，这种设计确保了服务的高可用性，避免了单点故障。 2. **加权负载均衡**：通过权重配置实现按能力分配请求，这种方式既充分利用了高能力通道，又避免了过载风险。 `─────────────────────────────────────────────────` ## 3. 协议转换 系统支持在不同 API 协议之间进行无缝转换。 ### A. 转换流程 ```mermaid sequenceDiagram participant C as 客户端 participant O as Octopus participant P as LLM 提供商 C->>O: OpenAI 格式请求 O->>O: 协议转换 O->>P: Anthropic 格式请求 P-->>O: Anthropic 格式响应 O->>O: 协议转换 O-->>C: OpenAI 格式响应 ```   ### B. 转换优势 - 客户端无需修改代码即可切换模型提供商 - 统一使用 OpenAI SDK 调用所有模型 - 降低多模型集成复杂度 ## 4. 价格管理 ### A. 数据来源 - 从 models.dev 自动同步模型价格 - 创建通道时自动添加新模型的价格信息 - 支持用户手动设置自定义价格 ### B. 价格优先级 | 优先级 | 来源 | 说明 | |-------|------|------| | 高 | 价格管理页面 | 用户手动设置的价格 | | 低 | models.dev | 自动同步的默认价格 | **★ Insight ─────────────────────────────────────** 1. **价格同步机制**：从 models.dev 自动获取价格数据，减少了手动维护工作，同时允许用户覆盖默认价格，兼顾了自动化和灵活性。 2. **统计数据批量写入**：统计数据先存储在内存中，定期批量写入数据库，这种设计避免了频繁 I/O 操作对性能的影响。 `─────────────────────────────────────────────────` ## 5. 统计分析 ### A. 统计指标 - 请求数量 - Token 消耗量 - 成本追踪 - 通道性能数据 ### B. 数据持久化策略 - 统计数据先存储在内存中 - 按配置的时间间隔批量写入数据库 - 程序正常退出时确保数据持久化 # 四、部署与配置 ## 1. 快速部署 ### A. Docker 部署 ```bash docker run -d --name octopus \ -v /path/to/data:/app/data \ -p 8080:8080 \ bestrui/octopus ``` ### B. Docker Compose 部署 ```bash wget https://raw.githubusercontent.com/bestruirui/octopus/refs/heads/dev/docker-compose.yml docker compose up -d ``` ## 2. 配置文件 配置文件默认位于 `data/config.json`，首次启动时自动生成。 ### A. 完整配置示例 ```json { "server": { "host": "0.0.0.0", "port": 8080 }, "database": { "type": "sqlite", "path": "data/data.db" }, "log": { "level": "info" } } ``` ### B. 数据库配置 | 数据库类型 | 配置值 | 连接字符串格式 | |-----------|-------|---------------| | SQLite | sqlite | data/data.db | | MySQL | mysql | user:password@tcp(host:port)/dbname | | PostgreSQL | postgres | postgresql://user:password@host:port/dbname?sslmode=disable | ## 3. 环境变量 所有配置选项均可通过环境变量覆盖，格式为 `OCTOPUS_` + 配置路径。 | 环境变量 | 配置选项 | 说明 | |---------|---------|------| | OCTOPUS_SERVER_PORT | server.port | 服务端口 | | OCTOPUS_SERVER_HOST | server.host | 监听地址 | | OCTOPUS_DATABASE_TYPE | database.type | 数据库类型 | | OCTOPUS_DATABASE_PATH | database.path | 数据库连接字符串 | | OCTOPUS_LOG_LEVEL | log.level | 日志级别 | # 五、客户端集成 ## 1. OpenAI SDK ```python from openai import OpenAI client = OpenAI( base_url="http://127.0.0.1:8080/v1", api_key="sk-octopus-your-api-key", ) completion = client.chat.completions.create( model="octopus-gpt-4o", messages=[ {"role": "user", "content": "你好"}, ], ) print(completion.choices[0].message.content) ``` ## 2. Claude Code 编辑 `~/.claude/settings.json`： ```json { "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:8080", "ANTHROPIC_AUTH_TOKEN": "sk-octopus-your-api-key", "ANTHROPIC_MODEL": "octopus-sonnet-4-5", "ANTHROPIC_SMALL_FAST_MODEL": "octopus-haiku-4-5" } } ``` ## 3. Codex 编辑 `~/.codex/config.toml`： ```toml model = "octopus-codex" model_provider = "octopus" [model_providers.octopus] name = "octopus" base_url = "http://127.0.0.1:8080/v1" ``` 编辑 `~/.codex/auth.json`： ```json { "OPENAI_API_KEY": "sk-octopus-your-api-key" } ``` **★ Insight ─────────────────────────────────────** 1. **统一接口设计**：通过 Octopus 作为中间层，所有客户端都可以使用统一的 API 格式调用不同提供商的模型，这种设计大大简化了多模型集成的复杂度。 2. **兼容性优先**：完全兼容 OpenAI SDK 和其他主流工具的接入方式，用户无需修改现有代码即可接入 Octopus。 `─────────────────────────────────────────────────` # 六、安全注意事项 ## 1. 默认凭据 - 默认用户名：admin - 默认密码：admin - 首次登录后必须立即修改密码 ## 2. 关闭注意事项 - 使用 Ctrl+C 或 SIGTERM 信号正常关闭 - 确保统计数据正确写入数据库 - 避免使用 kill -9 等强制终止方式 # 七、技术亮点 ## 1. 前端资源嵌入 前端构建产物嵌入到 Go 二进制文件中，部署时无需额外的前端服务器，简化了部署流程。 ## 2. 多数据库支持 支持 SQLite、MySQL、PostgreSQL，用户可以根据需求选择合适的数据库，从单机部署到集群部署均可覆盖。 ## 3. 智能统计数据管理 内存缓存 + 批量写入的策略，在保证数据完整性的同时，最大化了系统性能。 ## 4. 优雅的协议转换 支持多种主流 LLM API 协议的互转，降低了用户切换模型提供商的成本。 # 八、适用场景 ## 1. 个人开发者 - 需要同时使用多个 LLM 提供商 - 希望简化多模型调用流程 - 需要统一的成本管理和统计分析 ## 2. 小型团队 - 需要共享多个 API Key - 需要负载均衡提高可用性 - 需要统一的模型调用接口 ## 3. 应用集成 - 为应用提供统一的 LLM 接入层 - 降低多模型集成复杂度 - 便于模型切换和成本控制 *** ## 参考资料 1. [Octopus GitHub 仓库](https://github.com/bestruirui/octopus) 最后修改：2026 年 01 月 26 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏