ghcr.io/algorithmicsuperintelligence/optillm:v0.3.9-proxy-arm64

OptiLLM

🚀 零训练情况下推理任务准确率提升 2-10 倍

🤗 HuggingFace Space • 📓 Colab 演示 • 💬 讨论区

---

OptiLLM 是一个与 OpenAI API 兼容的优化推理代理，它实现了 20 多种最先进技术，可显著提高 LLM 在推理任务上的准确率和性能——无需任何模型训练或微调。

通过在推理时进行额外计算，使用这些技术可以在各种任务上超越前沿模型。Cerebras 的 CePO 方法 就是一个很好的将这些技术结合使用的例子。

✨ 核心特性

• 🎯 即时提升：数学、编码和逻辑推理任务准确率提升 2-10 倍
• 🔌 即插即用替代：适用于任何与 OpenAI 兼容的 API 端点
• 🧠 20 多种优化技术：从简单的 best-of-N 到高级的 MCTS 和规划
• 📦 无需训练：只需通过 OptiLLM 代理您现有的 API 调用
• ⚡ 生产就绪：已被全球企业和研究人员用于生产环境
• 🌍 多提供商支持：通过 LiteLLM 支持 OpenAI、Anthropic、Google、Cerebras 以及 100 多种模型

🚀 快速开始

通过 3 个简单步骤获得强大的推理能力提升：

# 1. 安装 OptiLLM
pip install optillm

# 2. 启动服务器
export OPENAI_API_KEY="your-key-here"
optillm

# 3. 与任何 OpenAI 客户端配合使用 - 只需更改模型名称！

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1")

# 添加 'moa-' 前缀启用 Mixture of Agents 优化
response = client.chat.completions.create(
model="moa-gpt-4o-mini",  # 这能让 GPT-4o-mini 达到 GPT-4o 的性能！
messages=[{"role": "user", "content": "求解：若 2x + 3 = 7，x 的值是多少？"}]
)

使用 OptiLLM 前："x = 1" ❌
使用 OptiLLM 后："让我逐步解答：2x + 3 = 7，所以 2x = 4，因此 x = 2" ✅

📊 验证结果

OptiLLM 在各种基准测试中均实现了可衡量的提升：

完整基准测试结果见下方 ⬇️

🏗️ 安装

使用 pip

pip install optillm
optillm
2024-10-22 07:45:05,612 - INFO - Loaded plugin: privacy
2024-10-22 07:45:06,293 - INFO - Loaded plugin: memory
2024-10-22 07:45:06,293 - INFO - Starting server with approach: auto

使用 Docker

docker pull ghcr.io/algorithmicsuperintelligence/optillm:latest
docker run -p 8000:8000 ghcr.io/algorithmicsuperintelligence/optillm:latest
2024-10-22 07:45:05,612 - INFO - Loaded plugin: privacy
2024-10-22 07:45:06,293 - INFO - Loaded plugin: memory
2024-10-22 07:45:06,293 - INFO - Starting server with approach: auto

可用的 Docker 镜像变体：

• 完整镜像 (latest): 包含本地推理和插件的所有依赖
• 仅代理 (latest-proxy): 轻量级镜像，无本地推理能力
• 离线版 (latest-offline): 自包含镜像，预下载模型（spaCy），支持完全离线运行

# 仅代理（最小镜像）
docker pull ghcr.io/algorithmicsuperintelligence/optillm:latest-proxy

# 离线版（最大镜像，包含预下载模型）
docker pull ghcr.io/algorithmicsuperintelligence/optillm:latest-offline

从源码安装

使用 git 克隆仓库，并通过 pip install 安装依赖。

git clone https://github.com/algorithmicsuperintelligence/optillm.git
cd optillm
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

🔒 SSL 配置

OptiLLM 支持 SSL 证书验证配置，可用于自签名证书或企业代理环境。

禁用 SSL 验证（仅开发环境）：

# 命令行
optillm --no-ssl-verify

# 环境变量
export OPTILLM_SSL_VERIFY=false
optillm

使用自定义 CA 证书：

# 命令行
optillm --ssl-cert-path /path/to/ca-bundle.crt

# 环境变量
export OPTILLM_SSL_CERT_PATH=/path/to/ca-bundle.crt
optillm

[!WARNING] 安全注意：禁用 SSL 验证不安全，仅应在开发环境中使用。对于使用自定义 CA 的生产环境，请改用 --ssl-cert-path。详情参见 SSL_CONFIGURATION.md。

已实现技术

已实现插件

我们支持所有主要的LLM提供商和推理模型。您需要设置正确的环境变量，代理将选择相应的客户端。

您可以按如下方式运行optillm代理：

python optillm.py
2024-09-06 07:57:14,191 - INFO - Starting server with approach: auto
2024-09-06 07:57:14,191 - INFO - Server configuration: {'approach': 'auto', 'mcts_simulations': 2, 'mcts_exploration': 0.2, 'mcts_depth': 1, 'best_of_n': 3, 'model': 'gpt-4o-mini', 'rstar_max_depth': 3, 'rstar_num_rollouts': 5, 'rstar_c': 1.4, 'base_url': '', 'host': '127.0.0.1'}
* Serving Flask app 'optillm'
* Debug mode: off
2024-09-06 07:57:14,212 - INFO - WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
* Running on http://127.0.0.1:8000
2024-09-06 07:57:14,212 - INFO - Press CTRL+C to quit

使用方法

代理运行后，只需将 base_url 设置为 http://localhost:8000/v1，即可将其作为 OpenAI 客户端的直接替代品使用。

import os
from openai import OpenAI

OPENAI_KEY = os.environ.get("OPENAI_API_KEY")
OPENAI_BASE_URL = "http://localhost:8000/v1"
client = OpenAI(api_key=OPENAI_KEY, base_url=OPENAI_BASE_URL)

response = client.chat.completions.create(
model="moa-gpt-4o",
messages=[
{
"role": "user",
"content": "Write a Python program to build an RL model to recite text from any position that the user provides, using only numpy."
}
],
temperature=0.2
)

print(response)

上述代码适用于 OpenAI 和 Azure OpenAI，只需记住使用正确的密钥填充 OPENAI_API_KEY 环境变量即可。

有多种方式可以控制优化技术，它们按以下优先级顺序应用：

• 可以通过在模型名称前添加标识符（slug）{slug}-model-name 来控制优化技术。例如，在上述代码中，我们使用 moa（即混合智能体）作为优化方法。在代理日志中，你将看到以下内容，显示 moa 与基础模型 gpt-4o-mini 一起使用。

2024-09-06 08:35:32,597 - INFO - Using approach moa, with gpt-4o-mini
2024-09-06 08:35:35,358 - INFO - HTTP Request: POST https://api.openai.com/v1/chat/completions "HTTP/1.1 200 OK"
2024-09-06 08:35:39,553 - INFO - HTTP Request: POST https://api.openai.com/v1/chat/completions "HTTP/1.1 200 OK"
2024-09-06 08:35:44,795 - INFO - HTTP Request: POST https://api.openai.com/v1/chat/completions "HTTP/1.1 200 OK"
2024-09-06 08:35:44,797 - INFO - 127.0.0.1 - - [06/Sep/2024 08:35:44] "POST /v1/chat/completions HTTP/1.1" 200 -

• 或者，可以在 extra_body 中的 optillm_approach 字段中传递标识符。

response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{ "role": "user","content": "" }],
temperature=0.2,
extra_body={"optillm_approach": "bon|moa|mcts"}
)

• 或者，只需在 system 或 user 提示中，使用 标签提及该方法即可。

response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{ "role": "user","content": " re2 How many r's are there in strawberry?" }],
temperature=0.2
)

[!TIP] 你还可以使用符号 & 和 | 组合不同的技术。使用 & 时，技术将按从左到右的顺序以管道方式处理，前一阶段的响应将作为下一阶段的请求。而使用 | 时，我们会并行运行所有请求，并生成多个响应作为列表返回。

请注意，上述约定仅在 optillm 服务器以推理方法设置为 auto 启动时才有效。否则，客户端请求中的 model 属性必须仅设置为模型名称。

我们现在支持所有 LLM 提供商（通过包装 LiteLLM SDK 实现）。例如，你可以将 moa 与 Gemini Flash 模型一起使用，方法是在环境变量 os.environ['GEMINI_API_KEY'] 中设置 API 密钥，然后调用模型 moa-gemini/gemini-1.5-flash-002。在输出中，你将看到 LiteLLM 被用于调用基础模型。

9:43:21 - LiteLLM:INFO: utils.py:2952 -
LiteLLM completion() model= gemini-1.5-flash-002; provider = gemini
2024-09-29 19:43:21,011 - INFO -
LiteLLM completion() model= gemini-1.5-flash-002; provider = gemini
2024-09-29 19:43:21,481 - INFO - HTTP Request: POST https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash-002:generateContent?key=[redacted] "HTTP/1.1 200 OK"
19:43:21 - LiteLLM:INFO: utils.py:988 - Wrapper: Completed Call, calling success_handler
2024-09-29 19:43:21,483 - INFO - Wrapper: Completed Call, calling success_handler
19:43:21 - LiteLLM:INFO: utils.py:2952 -
LiteLLM completion() model= gemini-1.5-flash-002; provider = gemini

[!TIP] optillm 是一个透明代理，可与任何具有 OpenAI API 兼容聊天补全端点的 LLM API 或提供商配合使用，反过来，optillm 也公开相同的 OpenAI API 兼容聊天补全端点。这使你能够轻松将其集成到任何现有工具或框架中。如果你想使用的 LLM 没有 OpenAI API 兼容端点（如 Google 或 Anthropic），可以使用 LiteLLM 代理服务器，它支持大多数 LLM。

以下序列图说明了请求和响应如何通过 optillm。

在图中：

• A 是现有工具（如 https://github.com/oobabooga/text-generation-webui/%EF%BC%89%E3%80%81%E6%A1%86%E6%9E%B6%EF%BC%88%E5%A6%82 https://github.com/patched-codes/patchwork%EF%BC%89%E6%88%96%E4%BD%A0%E8%87%AA%E5%B7%B1%E7%9A%84%E4%BB%A3%E7%A0%81%EF%BC%8C%E4%BD%A0%E5%B8%8C%E6%9C%9B%E5%9C%A8%E5%85%B6%E4%B8%AD%E4%BD%BF%E7%94%A8 optillm 的结果。你可以直接使用任何 OpenAI 客户端 SDK 来使用它。
• B 是 optillm 服务（直接运行或在 Docker 容器中运行），它将向 base_url 发送请求。
• C 是任何提供 OpenAI API 兼容聊天补全端点的服务。

Local inference server

我们支持在 optillm 中直接加载任何 HuggingFace 模型或 LoRA。要使用内置推理服务器，请将 OPTILLM_API_KEY 设置为任意值（例如 export OPTILLM_API_KEY="optillm"），然后在 OpenAI 客户端中使用相同的值。你可以在 model 字段中传递任何 HuggingFace 模型。如果是私有模型，请确保使用你的 HuggingFace 密钥设置 HF_TOKEN 环境变量。我们还支持通过 + 分隔符在模型之上添加任意数量的 LoRA。

例如，以下代码加载基础模型 meta-llama/Llama-3.2-1B-Instruct，然后在其之上添加两个 LoRA：patched-codes/Llama-3.2-1B-FixVulns 和 patched-codes/Llama-3.2-1B-FastApply。你可以通过 OpenAI SDK 客户端的 extra_body 字段中的 active_adapter 参数指定要使用的 LoRA。默认情况下，我们将加载最后指定的适配器。

OPENAI_BASE_URL = "http://localhost:8000/v1"
OPENAI_KEY = "optillm"
response = client.chat.completions.create(
model="meta-llama/Llama-3.2-1B-Instruct+patched-codes/Llama-3.2-1B-FastApply+patched-codes/Llama-3.2-1B-FixVulns",
messages=messages,
temperature=0.2,
logprobs = True,
top_logprobs = 3,
extra_body={"active_adapter": "patched-codes/Llama-3.2-1B-FastApply"},
)

你还可以直接在本地推理服务器上使用替代解码技术，如 cot_decoding（思维链解码）和 entropy_decoding（熵解码）。

MCP 插件

模型上下文协议（MCP）插件使 OptiLLM 能够连接 MCP 服务器，将外部工具、资源和提示词引入语言模型的上下文中。这支持与文件系统访问、数据库查询、API 连接等进行强大集成。

OptiLLM 通过多种传输方式支持本地和远程 MCP 服务器：

• stdio：本地服务器（传统方式）
• SSE：通过服务器发送事件（Server-Sent Events）的远程服务器
• WebSocket：通过 WebSocket 连接的远程服务器

什么是 MCP？

模型上下文协议（MCP）是一种开放协议标准，允许大型语言模型（LLMs）通过标准化接口安全访问工具和数据源。MCP 服务器可提供：

• 工具：可调用的函数，用于执行操作（如写入文件、查询数据库等）
• 资源：用于提供上下文的数据源（如文件内容）
• 提示词：特定用例的可重用提示词模板

配置

设置 MCP 配置

[!NOTE] 关于向后兼容性：现有的 MCP 配置将继续正常工作，无需更改。未指定 transport 字段时，默认值为 "stdio"，与现有设置保持完全向后兼容。

1. 在 ~/.optillm/mcp_config.json 创建配置文件，结构如下：

本地服务器（stdio）- 传统方式：

{
"mcpServers": {
"filesystem": {
"transport": "stdio",
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/path/to/allowed/directory1",
"/path/to/allowed/directory2"
],
"env": {},
"description": "Local filesystem access"
}
},
"log_level": "INFO"
}

旧版格式（仍可使用）：

{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
"env": {}
}
}
}

远程服务器（SSE）- 新功能：

{
"mcpServers": {
"github": {
"transport": "sse",
"url": "https://api.githubcopilot.com/mcp",
"headers": {
"Authorization": "Bearer ${GITHUB_TOKEN}",
"Accept": "text/event-stream"
},
"timeout": 30.0,
"sse_read_timeout": 300.0,
"description": "GitHub MCP server for repository access"
}
},
"log_level": "INFO"
}

远程服务器（WebSocket）- 新功能：

{
"mcpServers": {
"remote-ws": {
"transport": "websocket",
"url": "wss://api.example.com/mcp",
"description": "Remote WebSocket MCP server"
}
},
"log_level": "INFO"
}

混合配置（本地 + 远程）：

{
"mcpServers": {
"filesystem": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"],
"description": "Local filesystem access"
},
"github": {
"transport": "sse",
"url": "https://api.githubcopilot.com/mcp",
"headers": {
"Authorization": "Bearer ${GITHUB_TOKEN}"
},
"description": "GitHub MCP server"
},
"remote-api": {
"transport": "websocket",
"url": "wss://api.company.com/mcp",
"description": "Company internal MCP server"
}
},
"log_level": "INFO"
}

配置参数

通用参数：

• 服务器名称：服务器的唯一标识符（例如 "filesystem"、"github"）
• transport：传输方式 - "stdio"（默认）、"sse" 或 "websocket"
• description（可选）：服务器功能的描述
• timeout（可选）：连接超时时间（秒）（默认：5.0）

stdio 传输（本地服务器）：

• command：运行服务器的可执行文件
• args：服务器的命令行参数
• env：服务器进程的环境变量

sse 传输（服务器发送事件）：

• url：SSE 端点 URL
• headers（可选）：用于身份验证的 HTTP 头
• sse_read_timeout（可选）：SSE 读取超时时间（秒）（默认：300.0）

websocket 传输（WebSocket）：

• url：WebSocket 端点 URL

环境变量扩展： 头信息和其他字符串值支持使用 ${VARIABLE_NAME} 语法进行环境变量扩展。这对于 API 密钥尤其有用：

{
"headers": {
"Authorization": "Bearer ${GITHUB_TOKEN}",
"X-API-Key": "${MY_API_KEY}"
}
}

可用的 MCP 服务器

OptiLLM 支持本地和远程 MCP 服务器：

本地 MCP 服务器（stdio 传输）

您可以使用任何 官方 MCP 服务器 或作为本地进程运行的第三方服务器：

• 文件系统：@modelcontextprotocol/server-filesystem - 文件操作
• Git：mcp-server-git - Git 仓库操作
• SQLite：@modelcontextprotocol/server-sqlite - SQLite 数据库访问
• Brave 搜索：@modelcontextprotocol/server-brave-search - 网络搜索功能

远程 MCP 服务器（SSE/WebSocket 传输）

远程服务器提供集中式访问，无需本地安装：

• GitHub MCP 服务器：https://api.githubcopilot.com/mcp - 仓库管理、问题跟踪和代码分析
• 第三方服务器：任何支持 SSE 或 WebSocket 协议的 MCP 服务器

示例：综合配置

{
"mcpServers": {
"filesystem": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"],
"description": "Local file system access"
},
"search": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": {
"BRAVE_API_KEY": "your-api-key-here"
},
"description": "Web search capabilities"
},
"github": {
"transport": "sse",
"url": "https://api.githubcopilot.com/mcp",
"headers": {
"Authorization": "Bearer ${GITHUB_TOKEN}",
"Accept": "text/event-stream"
},
"description": "GitHub repository and issue management"
}
},
"log_level": "INFO"
}

Running with Docker

optillm 可以选择使用 Docker 和提供的 https://github.com/algorithmicsuperintelligence/optillm/blob/main/Dockerfile 进行构建和运行。

Using Docker Compose

1. 确保您的系统上已安装 Docker 和 Docker Compose。

2. 要么更新 docker-compose.yaml 文件中的环境变量，要么在项目根目录创建 .env 文件并添加您想要设置的任何环境变量。例如，要设置 OpenAI API 密钥，请在 .env 文件中添加以下行：

OPENAI_API_KEY=your_openai_api_key_here

3. 运行以下命令启动 optillm：

docker compose up -d

如果 Docker 镜像不存在，这将构建该镜像并启动 optillm 服务。

4. optillm 将在 http://localhost:8000 可用。

使用 Docker 时，您可以将这些参数设置为环境变量。例如，要设置方法和模型，您可以使用：

OPTILLM_APPROACH=mcts
OPTILLM_MODEL=gpt-4

要使用 API 密钥保护 optillm 代理，请设置 OPTILLM_API_KEY 环境变量：

OPTILLM_API_KEY=your_secret_api_key

当设置 API 密钥后，客户端必须在请求中使用 Authorization 头包含该密钥：

Authorization: Bearer your_secret_api_key

使用 optillm 在基准测试中的 SOTA 结果

MARS 在 AIME 2025、IMO 2025 和 LiveCodeBench 上的表现（2025 年 10 月）

模型：通过 OpenRouter 使用 google/gemini-2.5-flash-lite-preview-09-2025
配置：3 个智能体，2 轮验证，证明禁用思考标签

AutoThink 在 GPQA-Diamond 和 MMLU-Pro 上的表现（2025 年 5 月）

LongCePO 在 LongBench v2 上的表现（2025 年 4 月）

¹ 性能数据由 LongBench v2 作者报告，LongCePO 和 Llama-4-Maverick 的结果除外。
² LongCePO 的括号中数字表示 5 次运行的多数投票准确率。

LongCePO 在 HELMET - InfiniteBench En.MC（128K 长度）上的表现（2025 年 4 月）

¹ LongCePO 的括号中数字表示 5 次运行的多数投票准确率。

CePO 在数学和代码基准测试上的表现（2025 年 9 月）

CePO 在数学和代码基准测试上的表现（2025 年 3 月）

coc-claude-3-5-sonnet-20241022 在 AIME 2024 pass@1 上的表现（2024 年 11 月）

readurls&memory-gpt-4o-mini 在 Google FRAMES 基准测试上的表现（2024 年 10 月）

plansearch-gpt-4o-mini 在 LiveCodeBench 上的表现（2024 年 9 月）

moa-gpt-4o-mini 在 Arena-Hard-Auto 上的表现（2024 年 8 月）

optillm 与 Patchwork 集成（2024 年 7 月）

由于 optillm 是 OpenAI API 的即插即用替代品，您可以使用 OpenAI 客户端轻松将其与现有工具和框架集成。我们将 optillm 与 https://github.com/patched-codes/patchwork%EF%BC%88%E4%B8%80%E4%B8%AA%E5%BC%80%E6%BA%90%E6%A1%86%E6%9E%B6%EF%BC%8C%E9%80%9A%E8%BF%87%E7%A7%B0%E4%B8%BA patchflows 的工作流自动化 PR 审查、错误修复、安全补丁等开发杂务）一起使用。使用智能体混合方法（moa）时，我们观察到所有支持的 patchflows 都有显著的性能提升，如下所示。

测试

OptiLLM 包含全面的测试套件，以确保可靠性和兼容性。

运行测试

主测试套件可从项目根目录运行：

# 使用默认测试用例测试所有方法
python tests/test.py

# 测试特定方法
python tests/test.py --approaches moa bon mcts

# 运行单个测试
python tests/test.py --single-test "Simple Math Problem"

单元测试和集成测试