# llm-gateway **Repository Path**: orionis/llm-gateway ## Basic Information - **Project Name**: llm-gateway - **Description**: Squirrel LLM Gateway is a high-performance, enterprise-grade proxy service designed to unify and manage access to Large Language Model (LLM) providers like OpenAI and Anthropic. It provides intelligent routing, robust failover strategies, comprehensive logging, and a modern management dashboard. - **Primary Language**: Python - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-27 - **Last Updated**: 2026-04-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README ![cover](docs/assets/cover.jpg)

Squirrel

企业级 LLM 网关

面向 OpenAI、Anthropic 及兼容 API 的统一代理服务

English · 中文

Python 3.12+ FastAPI Next.js MIT License

## 概述 **Squirrel** 是一个高性能、生产就绪的代理服务，用于统一管理和访问多个大语言模型（LLM）供应商。它作为应用程序与 LLM 服务之间的智能网关，提供无缝的故障转移、负载均衡、全面的可观测性以及现代化的管理面板——现已原生支持 OpenAI Responses，并可在 OpenAI Chat、OpenAI Responses 与 Anthropic Messages 之间平滑转换。

### 为什么选择 Squirrel？ - **单一集成点**：一次接入，通过统一 API 访问多个 LLM 供应商 - **零代码改动**：完全兼容 OpenAI 和 Anthropic SDK，即插即用 - **成本优化**：基于规则、优先级或成本智能路由请求 - **生产就绪**：内置重试逻辑、故障转移机制和详细的请求日志 - **全面可见**：追踪每个请求的 Token 用量、延迟指标和成本分析 --- ## 核心特性 ### 统一 API 接口 - **兼容 OpenAI**：全面支持 `/v1/chat/completions`、`/v1/completions`、`/v1/embeddings`、`/v1/audio/*`、`/v1/images/*` - **兼容 OpenAI Responses**：支持 `/v1/responses`，含流式与工具调用 - **兼容 Anthropic**：原生支持 `/v1/messages` 端点 - **协议转换**：基于内置 `llm_api_converter`，实现 OpenAI Chat ↔ OpenAI Responses ↔ Anthropic Messages 的请求、响应与流式互转 - **流式支持**：完整的 Server-Sent Events (SSE) 支持，实现实时响应 ### 智能路由 - **规则路由**：基于模型名称、请求头、消息内容或 Token 数量路由请求 - **负载均衡策略**： - **轮询（Round-Robin）**：在供应商之间均匀分配请求 - **优先级（Priority）**：优先使用首选供应商，失败时回退到其他 - **权重（Weight）**：按自定义权重比例分配请求 - **最优成本（Cost-Based）**：根据 API 价格，自动选择价格最低的模型 - **模型映射**：将虚拟模型名称映射到多个后端供应商 ### 高可用 - **自动重试**：针对服务器错误（HTTP 500+）可配置重试次数 - **供应商故障转移**：失败时无缝切换到备用供应商 - **超时管理**：可配置的请求超时，支持长时间流式响应（默认：30 分钟） ### 全面可观测性 - **日志分层存储**：摘要字段保存在 `request_logs`，大体积的请求/响应载荷保存在 `request_log_details`，降低存储压力并提升日志列表查询性能 - **明细独立保留期**：请求/响应详情可以比摘要日志更早过期，在保留统计与审计能力的同时减少大字段长期占用 - **全量日志记录**：完整记录请求体和响应体（包括流式响应），便于问题追溯、调试及 AI 系统效果优化 - **Token 统计**：使用 [tiktoken](https://github.com/openai/tiktoken) 自动计算 Token 用量 - **延迟指标**：首字节延迟和总响应时间 - **成本分析**：按时间、模型、供应商和 API Key 聚合统计 - **数据脱敏**：日志中自动对敏感信息进行脱敏处理 ### 现代化管理面板 基于 **Next.js 16** + **TypeScript** + **shadcn/ui** 构建： - 供应商管理，支持连接测试 - 模型映射配置，内置规则编辑器 - API Key 生成和生命周期管理 - 高级日志查看器，支持多维度筛选 - 成本统计和用量分析 --- ## 快速开始 ### Docker Compose（推荐） 使用 PostgreSQL 的最快启动方式： ```bash # 克隆仓库 git clone https://github.com/mylxsw/llm-gateway.git cd llm-gateway # 启动服务 docker compose -f docker-compose.prod.yml up -d ``` 访问管理面板：**http://localhost:8000** ### Docker（单容器） 使用 SQLite 进行简单部署： ```bash docker run -d \ -p 8000:8000 \ -v $(pwd)/data:/data \ --name llm-gateway \ ghcr.io/mylxsw/llm-gateway:latest ``` ### 手动安装 #### 环境要求 - Python 3.12+ - Node.js 18+ - npm（用于前端） #### 后端设置 ```bash cd backend # 安装依赖（选择一种方式） uv sync # 推荐：使用 uv pip install -r requirements.txt # 或使用 pip # 初始化数据库 alembic upgrade head # 启动服务 uvicorn app.main:app --host 0.0.0.0 --port 8000 ``` #### 前端设置 ```bash cd frontend # 安装依赖 npm install # 开发模式 npm run dev # 生产构建 npm run build && npm run start ``` --- ## 使用方法 ### 基本配置 1. **添加供应商**：进入供应商页面，添加您的 LLM 供应商（如 OpenAI） - 设置基础 URL（如 `https://api.openai.com/v1`） - 添加您的 API Key - 选择协议类型（OpenAI、OpenAI Responses 或 Anthropic） 2. **创建模型映射**：进入模型页面创建映射 - 定义模型名称（如 `gpt-4`） - 关联一个或多个供应商 - 设置路由优先级/权重 3. **生成 API Key**：在 API Keys 页面创建网关 API Key 4. **连接您的应用**： ```python from openai import OpenAI client = OpenAI( base_url="http://localhost:8000/v1", api_key="lgw-your-gateway-api-key" ) response = client.chat.completions.create( model="gpt-4", messages=[{"role": "user", "content": "你好！"}] ) ``` #### OpenAI Responses 示例 ```python from openai import OpenAI client = OpenAI( base_url="http://localhost:8000/v1", api_key="lgw-your-gateway-api-key" ) response = client.responses.create( model="gpt-4.1-mini", input="请用一句话概括。" ) ``` ### API 端点 #### 代理端点（OpenAI 兼容） | 方法 | 端点 | 描述 | |------|------|------| | GET | `/v1/models` | 获取可用模型列表 | | POST | `/v1/chat/completions` | 对话补全 | | POST | `/v1/completions` | 文本补全 | | POST | `/v1/embeddings` | 生成向量嵌入 | | POST | `/v1/audio/speech` | 文字转语音 | | POST | `/v1/audio/transcriptions` | 语音转文字 | | POST | `/v1/audio/translations` | 语音转文字（翻译） | | POST | `/v1/images/generations` | 图像生成 | | POST | `/v1/responses` | Responses API | #### 代理端点（Anthropic 兼容） | 方法 | 端点 | 描述 | |------|------|------| | POST | `/v1/messages` | Messages API | #### 管理端点 | 资源 | 端点 | |------|------| | 供应商 | `GET/POST /api/admin/providers`，`GET/PUT/DELETE /api/admin/providers/{id}` | | 模型 | `GET/POST /api/admin/models`，`GET/PUT/DELETE /api/admin/models/{model}` | | API Keys | `GET/POST /api/admin/api-keys`，`GET/PUT/DELETE /api/admin/api-keys/{id}` | | 日志 | `GET /api/admin/logs`，`GET /api/admin/logs/stats` | 完整 API 文档请参阅 [docs/api.md](docs/api.md)。 --- ## 配置说明 ### 环境变量 | 变量 | 默认值 | 描述 | |------|--------|------| | `APP_NAME` | LLM Gateway | 应用名称 | | `DEBUG` | false | 启用调试模式 | | `DATABASE_TYPE` | sqlite | 数据库类型：`sqlite` 或 `postgresql` | | `DATABASE_URL` | sqlite+aiosqlite:///./llm_gateway.db | 数据库连接字符串 | | `RETRY_MAX_ATTEMPTS` | 3 | 500+ 错误的最大重试次数 | | `RETRY_DELAY_MS` | 1000 | 重试间隔（毫秒） | | `HTTP_TIMEOUT` | 1800 | 上游请求超时（秒） | | `API_KEY_PREFIX` | lgw- | 生成的 API Key 前缀 | | `API_KEY_LENGTH` | 32 | 生成的 API Key 长度 | | `ENCRYPTION_KEY` | - | 用于加密存储敏感字段的 32 字节 Base64 密钥（重启后必须保持不变） | | `ENABLE_VIEW_API_KEYS` | false | 是否允许在 API Keys 页面再次查看/复制完整 API Key | | `RATE_LIMIT_ENABLED` | false | 启用/禁用内置限流中间件 | | `ADMIN_USERNAME` | - | 管理员登录用户名（可选） | | `ADMIN_PASSWORD` | - | 管理员登录密码（可选） | | `ADMIN_TOKEN_TTL_SECONDS` | 86400 | 管理员会话有效期（24 小时） | | `LOG_RETENTION_DAYS` | 7 | 日志保留天数 | | `LOG_DETAIL_RETENTION_DAYS` | 7 | 请求/响应大字段明细的保留天数，必须小于或等于 `LOG_RETENTION_DAYS` | | `LOG_CLEANUP_INTERVAL_HOURS` | 24 | 定时日志清理的执行间隔（小时） | | `LLM_GATEWAY_PORT` | 8000 | Docker Compose 主机端口 | | `KV_STORE_TYPE` | database | KV 存储后端：`database` 或 `redis` | | `REDIS_URL` | - | Redis 连接 URL（使用 Redis KV 存储时） | ### 日志保留行为 - `LOG_RETENTION_DAYS` 控制摘要日志保留多久。 - `LOG_DETAIL_RETENTION_DAYS` 控制请求/响应大字段明细保留多久。 - 明细过期后，日志列表和统计仍然可用，但请求体、请求头、上游载荷，以及基于这些数据的重试与 Playground 调试能力将不可用。 - 定时清理按照 `LOG_CLEANUP_INTERVAL_HOURS` 周期执行。 生成加密密钥： ```bash python -c "import secrets, base64; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())" ``` 在 `.env` 中设置（生产环境必填）： ```env ENCRYPTION_KEY=your-generated-key ``` ### 数据库配置 **SQLite**（默认，简单部署）： ```env DATABASE_TYPE=sqlite DATABASE_URL=sqlite+aiosqlite:///./llm_gateway.db ``` **PostgreSQL**（推荐用于生产环境）： ```env DATABASE_TYPE=postgresql DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/llm_gateway ``` --- ## 支持的供应商 Squirrel 可以代理任何 OpenAI 或 Anthropic 兼容的 API： | 供应商 | 协议 | 说明 | |--------|------|------| | OpenAI | OpenAI | 全面支持 GPT-4、GPT-3.5、嵌入、语音、图像 | | OpenAI | OpenAI Responses | 通过 `/v1/responses` 提供 Responses API | | Anthropic | Anthropic | 通过 Messages API 支持 Claude 模型 | | Azure OpenAI | OpenAI | 使用 Azure 端点 URL | | 本地模型 | OpenAI | Ollama、vLLM、LocalAI 等 | | 其他供应商 | OpenAI/Anthropic | 任何兼容的 API 端点 | --- ## 开发指南 ### 项目结构 ``` llm-gateway/ ├── backend/ │ ├── app/ │ │ ├── api/ # API 路由（代理、管理） │ │ ├── services/ # 业务逻辑 │ │ ├── providers/ # 协议适配器 │ │ ├── repositories/ # 数据访问层 │ │ ├── db/ # 数据库模型 │ │ ├── domain/ # DTO 和领域模型 │ │ ├── rules/ # 规则评估引擎 │ │ └── common/ # 工具类 │ ├── migrations/ # Alembic 数据库迁移 │ └── tests/ # 测试套件 ├── llm_api_converter/ # 协议转换 SDK（OpenAI/Responses/Anthropic） ├── frontend/ │ └── src/ │ ├── app/ # Next.js App Router 页面 │ ├── components/ # React 组件 │ └── lib/ # 工具类和 API 客户端 ├── docker-compose.yml └── Dockerfile ``` ### 运行测试 ```bash cd backend pytest ``` ### 数据库迁移 ```bash cd backend # 创建新的迁移 alembic revision --autogenerate -m "description" # 应用迁移 alembic upgrade head ``` --- ## 文档 - [架构设计](docs/architecture.md) - [API 参考](docs/api.md) - [模块详情](docs/modules.md) - [协议转换](docs/protocol_conversion.md) - [需求文档](docs/req.md) --- ## 许可证 [MIT](LICENSE) ---

为 LLM 社区用心打造