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. 技术栈

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. 协议类型支持

★ Insight ─────────────────────────────────────

1. 自动路径拼接设计：用户只需提供基础 URL，系统根据通道类型自动追加 API 路径，这种设计降低了配置复杂度，减少了用户错误。
2. 多端点智能选择：通过实时监测各端点延迟，自动选择最优路径，这种动态优化机制能有效提升用户体验。
   ─────────────────────────────────────────────────

2. 分组管理与负载均衡

分组将多个通道聚合为一个统一的外部模型名称。

A. 负载均衡模式

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. 转换流程

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. 价格优先级

★ Insight ─────────────────────────────────────

1. 价格同步机制：从 models.dev 自动获取价格数据，减少了手动维护工作，同时允许用户覆盖默认价格，兼顾了自动化和灵活性。
2. 统计数据批量写入：统计数据先存储在内存中，定期批量写入数据库，这种设计避免了频繁 I/O 操作对性能的影响。
   ─────────────────────────────────────────────────

5. 统计分析

A. 统计指标

• 请求数量
• Token 消耗量
• 成本追踪
• 通道性能数据

B. 数据持久化策略

• 统计数据先存储在内存中
• 按配置的时间间隔批量写入数据库
• 程序正常退出时确保数据持久化

四、部署与配置

1. 快速部署

A. Docker 部署

docker run -d --name octopus \
  -v /path/to/data:/app/data \
  -p 8080:8080 \
  bestrui/octopus

B. Docker Compose 部署

wget https://raw.githubusercontent.com/bestruirui/octopus/refs/heads/dev/docker-compose.yml
docker compose up -d

2. 配置文件

配置文件默认位于 data/config.json，首次启动时自动生成。

A. 完整配置示例

{
  "server": {
    "host": "0.0.0.0",
    "port": 8080
  },
  "database": {
    "type": "sqlite",
    "path": "data/data.db"
  },
  "log": {
    "level": "info"
  }
}

B. 数据库配置

3. 环境变量

所有配置选项均可通过环境变量覆盖，格式为 OCTOPUS_ + 配置路径。

五、客户端集成

1. OpenAI SDK

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：

{
  "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：

model = "octopus-codex"
model_provider = "octopus"

[model_providers.octopus]
name = "octopus"
base_url = "http://127.0.0.1:8080/v1"

编辑 ~/.codex/auth.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 仓库