OptiLLM

🚀 在推理任务上实现零训练下的2-10倍准确率提升

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

---

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

通过在推理阶段增加计算资源，这些技术可以在各种任务中超越前沿模型。Cerebras 提出的 CePO 方法 就是一个将这些技术有效结合的良好范例。

✨ 核心特性

• 🎯 即时提升: 在数学、编码和逻辑推理方面实现 2-10 倍的准确率提升
• 🔌 即插即用: 可与任何兼容 OpenAI API 的端点配合使用
• 🧠 20+ 优化技术: 从简单的最佳 N 抽样到高级的 MCTS 和规划方法
• 📦 无需训练: 只需将现有的 API 调用通过 OptiLLM 进行代理即可
• ⚡ 生产就绪: 已被全球多家公司和研究机构用于生产环境
• 🌍 多提供商支持: 支持 OpenAI、Anthropic、Google、Cerebras 等，并可通过 LiteLLM 使用 100 多种模型

🚀 快速入门

只需三个简单步骤，即可获得强大的推理能力提升：

# 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-' 前缀以启用混合代理优化
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 在多种基准测试中均表现出可量化的提升：

技术	基础模型	提升幅度	基准测试
MARS	Gemini 2.5 Flash Lite	+30.0 分	AIME 2025 (43.3→73.3)
CePO	Llama 3.3 70B	+18.6 分	Math-L5 (51.0→69.6)
AutoThink	DeepSeek-R1-1.5B	+9.34 分	GPQA-Diamond (21.72→31.06)
LongCePO	Llama 3.3 70B	+13.6 分	InfiniteBench (58.0→71.6)
MOA	GPT-4o-mini	媲美 GPT-4	Arena-Hard-Auto
PlanSearch	GPT-4o-mini	Pass@5 提升 20%	LiveCodeBench

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

🏗️ 安装

使用 pip

pip install optillm
optillm
2024-10-22 07:45:05,612 - INFO - 加载了隐私插件
2024-10-22 07:45:06,293 - INFO - 加载了记忆插件
2024-10-22 07:45:06,293 - INFO - 使用自动方法启动服务器

使用 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 - 加载了隐私插件
2024-10-22 07:45:06,293 - INFO - 加载了记忆插件
2024-10-22 07:45:06,293 - INFO - 使用自动方法启动服务器

可用的 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

⚠️ 安全提示: 禁用 SSL 验证是不安全的，仅应在开发环境中使用。对于使用自定义 CA 的生产环境，请改用 --ssl-cert-path。详细信息请参阅 SSL_CONFIGURATION.md。

已实现的技术

方法	Slug	描述
MARS（多智能体推理系统）	mars	多智能体推理，结合多样化的温度探索、交叉验证和迭代改进
Cerebras 规划与优化	cepo	结合最佳N个结果、思维链、自我反思、自我改进以及多种提示技术
带反思的思维链	cot_reflection	实现带有<thinking>、<reflection>和<output>部分的思维链推理
计划搜索	plansearch	在自然语言中对候选计划实施搜索算法以解决问题
重读	re2	通过两次处理查询来改进推理，实现重读功能
自一致性	self_consistency	实现一种先进的自一致性方法
Z3 定理证明器	z3	利用Z3定理证明器进行逻辑推理
R* 算法	rstar	实现R*算法用于问题求解
LEAP	leap	从少量示例中学习特定任务的原则
往返优化	rto	通过往返过程优化响应
最佳N采样	bon	生成多个响应并选择最佳的一个
智能体混合	moa	综合多个批评意见的响应
蒙特卡洛树搜索	mcts	在聊天回复中使用蒙特卡洛树搜索进行决策
PV 游戏	pvg	在推理时应用证明者-验证者博弈的方法
Deep Confidence	代理不适用	实现基于置信度的推理，采用多级强度以提升准确性
思维链解码	代理不适用	实现思维链解码，以在无需显式提示的情况下引导推理
熵解码	代理不适用	在生成过程中根据标记的不确定性实施自适应采样
Thinkdeeper	代理不适用	实现来自OpenAI的reasoning_effort参数，适用于DeepSeek R1等推理模型
AutoThink	代理不适用	将查询复杂度分类与引导向量相结合，以增强推理能力

已实现插件

插件	Slug	描述
系统提示学习	spl	实现了Andrej Karpathy 所称的第三范式 的 LLM 学习方法，使模型能够获取解题知识和策略
深度思考	deepthink	使用推理时缩放技术，为推理型 LLM 实现类似 Gemini 的深度思考方法
长上下文 Cerebras 规划与优化	longcepo	结合规划和分治处理长文档，以支持无限上下文长度
多数投票	majority_voting	生成 k 个候选解决方案，并通过多数投票选出最频繁的答案（默认 k=6）
MCP 客户端	mcp	实现模型上下文协议 (MCP) 客户端，使您能够将任何 LLM 与任何 MCP 服务器配合使用
路由器	router	使用 optillm-modernbert-large 模型，根据用户提示将请求路由到不同的方法
代码链	coc	实现一种结合思维链与代码执行及 LLM 基于代码模拟的代码链方法
内存	memory	实现短期记忆层，使您能够与任何 LLM 配合使用无限制的上下文长度
隐私	privacy	对请求中的 PII 数据进行匿名化处理，并在响应中将其还原为原始值
读取 URL	readurls	读取请求中找到的所有 URL，获取 URL 上的内容并将其添加到上下文中
执行代码	executecode	允许在请求和 LLM 生成的响应中使用代码解释器执行 Python 代码
JSON	json	使用 outlines 库实现结构化输出，支持 Pydantic 类型和 JSON Schema
生成选择	genselect	生成式解决方案选择——生成多个候选方案，并根据质量标准选出最佳方案
网络搜索	web_search	使用 Chrome 自动化工具（Selenium）进行 Google 搜索，收集搜索结果和 URL
深度研究	deep_research	实现测试时扩散深度研究员（TTD-DR），通过迭代精炼生成全面的研究报告
代理	proxy	在多个 LLM 提供商之间实现负载均衡和故障转移，具备健康监测和轮询路由功能

我们支持所有主要的 LLM 提供商及其模型进行推理。您只需设置正确的环境变量，代理就会自动选择相应的客户端。

提供商	必需环境变量	附加说明
OptiLLM	OPTILLM_API_KEY	使用内置本地服务器进行推理，支持 logprobs 以及如 cot_decoding 和 entropy_decoding 等解码技术
OpenAI	OPENAI_API_KEY	您可以通过设置 base_url 将其与任何兼容 OpenAI 的端点（例如 OpenRouter）一起使用
Cerebras	CEREBRAS_API_KEY	您可以使用它来对受支持的模型进行快速推理，请参阅文档了解详情
Azure OpenAI	AZURE_OPENAI_API_KEY AZURE_API_VERSION AZURE_API_BASE	-
Azure OpenAI（托管身份）	AZURE_API_VERSION AZURE_API_BASE	需要使用 az login 登录，请参阅文档了解详情
LiteLLM	取决于模型	请参阅文档了解详情

随后，您可以按如下方式运行 optillm 代理。

python optillm.py
2024-09-06 07:57:14,191 - INFO - 启动服务器，采用自动模式
2024-09-06 07:57:14,191 - INFO - 服务器配置：{'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'}
 * 正在提供 Flask 应用程序 'optillm'
 * 调试模式：关闭
2024-09-06 07:57:14,212 - INFO - 警告：这是一个开发服务器。请勿在生产环境中使用。请改用生产级 WSGI 服务器。
 * 运行于 http://127.0.0.1:8000
2024-09-06 07:57:14,212 - INFO - 按 CTRL+C 退出

安全提示：默认情况下，optillm 绑定到 127.0.0.1（仅限本地），以确保安全性。若需允许外部连接（例如用于 Docker 或远程访问），请使用 --host 0.0.0.0。但仅应在受信任的网络上或已通过 --optillm-api-key 配置适当的身份验证后才这样做。

使用方法

代理服务启动后，您可以通过将 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": "请编写一个 Python 程序，仅使用 numpy 构建一个强化学习模型，使其能够从用户指定的任意位置开始朗读文本。"
    }
  ],
  temperature=0.2
)

print(response)

上述代码适用于 OpenAI 和 Azure OpenAI，只需确保将 OPENAI_API_KEY 环境变量设置为正确的 API 密钥即可。

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

• 您可以通过在模型名称前添加标识符 {slug}-model-name 来指定使用的优化技术。例如，在上面的代码中，我们使用了 moa（即混合代理）作为优化方法。在代理的日志中，您会看到类似以下内容，表明正在使用 moa 技术，并以 gpt-4o-mini 作为基础模型：

2024-09-06 08:35:32,597 - INFO - 使用 moa 方法，基础模型为 gpt-4o-mini
2024-09-06 08:35:35,358 - INFO - HTTP 请求：POST https://api.openai.com/v1/chat/completions "HTTP/1.1 200 OK"
2024-09-06 08:35:39,553 - INFO - HTTP 请求：POST https://api.openai.com/v1/chat/completions "HTTP/1.1 200 OK"
2024-09-06 08:35:44,795 - INFO - HTTP 请求：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 提示中，使用 <optillm_approach> </optillm_approach> 标签来指定优化方法。

response = client.chat.completions.create(
  model="gpt-4o-mini",
  messages=[{ "role": "user","content": "<optillm_approach>re2</optillm_approach> 草莓这个词中有多少个 r？" }],
  temperature=0.2
)

[!提示] 您还可以结合不同的技术，使用符号 & 和 |。当使用 & 时，技术会按照从左到右的顺序依次处理，前一阶段的响应将作为下一阶段的请求输入。而使用 | 时，则会并行执行所有请求，并返回多个响应结果，以列表形式呈现。

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

目前，我们支持所有 LLM 提供商（通过封装 LiteLLM SDK 实现）。例如，您可以将 Gemini Flash 模型与 moa 结合使用，只需在环境变量中设置 os.environ['GEMINI_API_KEY']，然后调用模型 moa-gemini/gemini-1.5-flash-002。在输出中，您会看到 LiteLLM 正在用于调用基础模型。

9:43:21 - LiteLLM:INFO: utils.py:2952 -
LiteLLM completion() 模型= gemini-1.5-flash-002；提供商 = gemini
2024-09-29 19:43:21,011 - INFO -
LiteLLM completion() 模型= gemini-1.5-flash-002；提供商 = gemini
2024-09-29 19:43:21,481 - INFO - HTTP 请求：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 - 包装器：调用完成，正在调用成功处理程序
2024-09-29 19:43:21,483 - INFO - 包装器：调用完成，正在调用成功处理程序
19:43:21 - LiteLLM:INFO: utils.py:2952 -
LiteLLM completion() 模型= gemini-1.5-flash-002；提供商 = gemini

[!提示] optillm 是一个透明代理，可与任何具有 OpenAI API 兼容聊天补全端点的 LLM API 或提供商配合使用，同时 optillm 本身也暴露了一个兼容 OpenAI API 的聊天补全端点。这使得您可以轻松地将其集成到任何现有工具或框架中。如果您想要使用的 LLM 不具备 OpenAI API 兼容端点（如 Google 或 Anthropic），可以使用 LiteLLM 代理服务器，它支持大多数 LLM。

以下序列图展示了请求和响应如何通过 optillm 流转：

在图中：

• A 是现有的工具（如 oobabooga）、框架（如 patchwork）或您自己的代码，您希望从中获取 optillm 的结果。您可以直接使用任何 OpenAI 客户端 SDK 来访问它。
• B 是 optillm 服务（可以直接运行或在 Docker 容器中运行），它会向 base_url 发送请求。
• C 是任何提供 OpenAI API 兼容聊天补全端点的服务。

本地推理服务器

我们支持在 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。

response = client.chat.completions.create(
  model="meta-llama/Llama-3.2-1B-Instruct",
  messages=messages,
  temperature=0.2,
  extra_body={
        "decoding": "cot_decoding",  # 或 "entropy_decoding"
        // CoT 特定参数
        "k": 10,
        "aggregate_paths": True,
        // 或者熵解码特定参数
        "top_k": 27,
        "min_p": 0.03,
    }
)

使用外部服务器（如 llama.cpp 或 ollama）启动 optillm 代理

• 将 OPENAI_API_KEY 环境变量设置为占位符值：
  • 例如 export OPENAI_API_KEY="sk-no-key"
• 运行 ./llama-server -c 4096 -m path_to_model 来启动服务器，指定模型和 4096 个 token 的上下文长度。
• 运行 python3 optillm.py --base_url base_url 来启动代理：
  • 例如，对于 llama.cpp，运行 python3 optillm.py --base_url http://localhost:8080/v1。

[!警告] Anthropic API、llama.cpp 服务器和 ollama 目前不支持从模型中采样多个响应，这限制了可用的方法仅限于以下几种： cot_reflection、leap、plansearch、rstar、rto、self_consistency、re2 和 z3。对于 HuggingFace 上的模型，你可以使用内置的本地推理服务器，因为它支持多响应。

MCP 插件

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

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

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

什么是 MCP？

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

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

配置

设置 MCP 配置

关于向后兼容性的说明：现有的 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": "本地文件系统访问"
    }
  },
  "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 服务器，用于仓库访问"
    }
  },
  "log_level": "INFO"
}

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

{
  "mcpServers": {
    "remote-ws": {
      "transport": "websocket",
      "url": "wss://api.example.com/mcp",
      "description": "远程 WebSocket MCP 服务器"
    }
  },
  "log_level": "INFO"
}

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

{
  "mcpServers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"],
      "description": "本地文件系统访问"
    },
    "github": {
      "transport": "sse",
      "url": "https://api.githubcopilot.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      },
      "description": "GitHub MCP 服务器"
    },
    "remote-api": {
      "transport": "websocket",
      "url": "wss://api.company.com/mcp",
      "description": "公司内部 MCP 服务器"
    }
  },
  "log_level": "INFO"
}

配置参数

通用参数：

• 服务器名称：服务器的唯一标识符（如“filesystem”、“github”）
• 传输方式：传输方法——“stdio”（默认）、“sse”或“websocket”
• 描述（可选）：服务器功能的描述
• 超时时间（可选）：连接超时时间，单位为秒（默认：5.0）

stdio 传输（本地服务器）：

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

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

• URL：SSE 端点 URL
• 头信息（可选）：用于身份验证的 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": "本地文件系统访问"
    },
    "search": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-api-key-here"
      },
      "description": "网络搜索功能"
    },
    "github": {
      "transport": "sse",
      "url": "https://api.githubcopilot.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}",
        "Accept": "text/event-stream"
      },
      "description": "GitHub 仓库和问题管理"
    }
  },
  "log_level": "INFO"
}

使用 MCP 插件

配置完成后，MCP 插件将自动：

1. 连接到所有已配置的 MCP 服务器
2. 发现可用的工具、资源和提示
3. 将这些能力提供给语言模型
4. 处理工具调用和资源请求

插件会通过 MCP 能力增强系统提示，使模型知道有哪些工具可用。当模型决定使用某个工具时，插件会：

1. 使用提供的参数执行该工具
2. 将结果返回给模型
3. 允许模型将结果整合到其响应中

查询示例

以下是一些会触发 MCP 工具的查询示例：

本地服务器示例：

• “列出我文档目录中的所有 Python 文件”（文件系统）
• “我的 Git 仓库最近有哪些提交？”（Git）
• “搜索关于可再生能源的最新信息”（搜索）
• “查询我的数据库中本月注册的所有用户”（数据库）

远程服务器示例：

• “展示我 GitHub 仓库中的未解决问题”（GitHub MCP）
• “为我正在开发的功能创建一个新分支”（GitHub MCP）
• “有哪些最近的拉取请求需要评审？”（GitHub MCP）
• “获取我远程仓库中的文件内容”（GitHub MCP）

故障排除

日志

MCP 插件会将详细信息记录到：

~/.optillm/logs/mcp_plugin.log

请检查此日志文件以了解连接问题、工具执行错误及其他诊断信息。

常见问题

本地服务器问题（stdio 传输）：

1. 命令未找到：确保服务器可执行文件在您的 PATH 中可用，或在配置中使用绝对路径。

2. 权限不足：对于文件系统操作，请确保配置中指定的路径对进程是可访问的。

远程服务器问题（SSE/WebSocket 传输）：

3. 连接超时：远程服务器可能需要更长时间才能建立连接。请增加配置中的 timeout 值。

4. 认证失败：请验证您的 API 密钥和令牌是否正确。对于 GitHub MCP 服务器，确保已设置具有适当权限的 GITHUB_TOKEN 环境变量。

5. 网络错误：请检查您的互联网连接，并确认服务器 URL 是否可访问。

6. 未找到环境变量：如果使用 ${VARIABLE_NAME} 语法，请确保在启动 OptILLM 之前已设置相应的环境变量。

通用问题：

7. 方法未找到：某些服务器并未实现所有 MCP 功能（工具、资源、提示）。请确认服务器支持哪些功能。

8. 不支持的传输方式：请确保您使用的是受支持的传输方式：“stdio”、“sse”或“websocket”。

示例：测试 GitHub MCP 连接

要测试您的 GitHub MCP 服务器配置是否正常工作：

1. 设置您的 GitHub 令牌：export GITHUB_TOKEN="your-github-token"
2. 启动 OptILLM 并查看 ~/.optillm/logs/mcp_plugin.log 中的日志
3. 查找连接成功的消息以及发现的能力

可用参数

optillm 支持多种命令行参数进行配置。在使用 Docker 时，这些参数也可以作为以 OPTILLM_ 为前缀的环境变量来设置。

参数	描述	默认值
--approach	使用的推理方法	"auto"
--simulations	MCTS 模拟次数	2
--exploration	MCTS 的探索权重	0.2
--depth	MCTS 的模拟深度	1
--best-of-n	best_of_n 方法的样本数量	3
--model	使用的 OpenAI 模型	"gpt-4o-mini"
--base-url	OpenAI 兼容端点的基础 URL	""
--rstar-max-depth	rStar 算法的最大深度	3
--rstar-num-rollouts	rStar 算法的模拟次数	5
--rstar-c	rStar 算法的探索常数	1.4
--n	最终返回的回答数量	1
--return-full-response	返回包含思维链（CoT）及 <thinking> 标签的完整响应	False
--port	指定代理服务运行的端口	8000
--optillm-api-key	客户端认证 optillm 的可选 API 密钥	""
--cepo_*	详细配置选项请参阅下方的 CePO 参数部分	各种

CePO 参数

参数	描述	默认值
--cepo_bestofn_n	在 best of n 阶段生成的回答数量	3
--cepo_bestofn_temperature	在 best of n 阶段验证器的温度	0.1
--cepo_bestofn_max_tokens	在 best of n 阶段验证器的最大令牌数	4096
--cepo_bestofn_rating_type	在 best of n 阶段的评分类型（“绝对”或“成对”）	"absolute"
--cepo_planning_n	在规划阶段生成的计划数量	3
--cepo_planning_m	在规划阶段尝试生成 n 个计划的次数	6
--cepo_planning_temperature_step1	规划阶段第一步生成器的温度	0.55
--cepo_planning_temperature_step2	规划阶段第二步生成器的温度	0.25
--cepo_planning_temperature_direct_resp	如果规划失败并直接作答，第二步后生成器的温度	0.1
--cepo_planning_temperature_step3	规划阶段第三步生成器的温度	0.1
--cepo_planning_temperature_step4	规划阶段第四步生成器的温度	0
--cepo_planning_max_tokens_step1	规划阶段第一步的最大令牌数	4096
--cepo_planning_max_tokens_step2	规划阶段第二步的最大令牌数	4096
--cepo_planning_max_tokens_direct_resp	如果规划失败并直接作答，第二步后的最大令牌数	4096
--cepo_planning_max_tokens_step3	规划阶段第三步的最大令牌数	4096
--cepo_planning_max_tokens_step4	规划阶段第四步的最大令牌数	4096
--cepo_use_reasoning_fallback	当高级推理失败时是否回退到低级推理	False
--cepo_num_of_retries	LLM 调用失败时的重试次数，0 表示不重试	0
--cepo_print_output	是否打印每个阶段的输出	False
--cepo_config_file	CePO 配置文件的路径	None
--cepo_use_plan_diversity	是否使用额外的计划多样性步骤	False
--cepo_rating_model	如果评分步骤使用的模型与完成步骤不同，则指定评分模型	None

使用 Docker 运行

optillm 可以选择使用 Docker 和提供的 Dockerfile 进行构建和运行。

使用 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 月）上的表现

基准测试	方法	题目数量	正确答案数	准确率	提升幅度
AIME 2025	基线	30	13	43.3%	-
AIME 2025	MARS	30	22	73.3%	+30.0pp (+69.2%)
IMO 2025	基线	6	1	16.7%	-
IMO 2025	MARS	6	2	33.3%	+16.7pp (+100%)
LiveCodeBench v5/v6	基线	105	41	39.05%	-
LiveCodeBench v5/v6	MARS	105	53	50.48%	+11.43pp (+29.3%)

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

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

模型	GPQA-Diamond		MMLU-Pro
	准确率 (%)	平均 token 数	准确率 (%)	平均 token 数
DeepSeek-R1-Distill-Qwen-1.5B	21.72	7868.26	25.58	2842.75
固定预算下	28.47	3570.00	26.18	1815.67
AutoThink 下	31.06	3520.52	26.38	1792.50

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

模型¹	上下文窗口	短样本（最多32K词）	中等样本（32–128K词）
Llama 3.3 70B Instruct	128K	36.7 (45.0)	27.0 (33.0)
LongCePO + Llama 3.3 70B Instruct	8K	36.8 ± 1.38	38.7 ± 2.574 (39.735)²
Mistral-Large-Instruct-2411	128K	41.7 (46.1)	30.7 (34.9)
o1-mini-2024-09-12	128K	48.6 (48.9)	33.3 (32.9)
Claude-3.5-Sonnet-20241022	200K	46.1 (53.9)	38.6 (41.9)
Llama-4-Maverick-17B-128E-Instruct	524K	32.22 (50.56)	28.84 (41.86)

¹ 性能数据由 LongBench v2 的作者提供，除 LongCePO 和 Llama-4-Maverick 的结果外。

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

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

模型	准确率 (%)
Llama 3.3 70B Instruct （完整上下文）	58.0
LongCePO + Llama 3.3 70B Instruct（8K 上下文）	71.6 ± 1.855（73.0）¹
o1-mini-2024-09-12（完整上下文）	58.0
gpt-4o-2024-08-06（完整上下文）	74.0

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

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

方法	AIME 2024	AIME 2025	GPQA	LiveCodeBench
Qwen3 8B	74.0	68.3	59.3	55.7
CePO（使用 Qwen3 8B）	86.7	80.0	62.5	60.5
Qwen3 32B	81.4	72.9	66.8	65.7
CePO（使用 Qwen3 32B）	90.7	83.3	70.0	71.9
Qwen3 235B	85.7	81.5	71.1	70.7
DeepSeek R1	79.8	70.0	71.5	64.3
OpenAI o3-mini	79.6	74.8	76.8	66.3
Grok3 Think	83.9	77.3	80.2	70.6

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

方法	Math-L5	MMLU-Pro（数学）	CRUX	LiveCodeBench（pass@1）	Simple QA
Llama 3.3 70B	51.0	78.6	72.6	27.1	20.9
Llama 3.1 405B	49.8	79.2	73.0	31.8	13.5
CePO（使用 Llama 3.3 70B）	69.6	84.8	80.1	31.9	22.6
QwQ 32B	61.4	90.8	82.5	44.3	7.8
CePO（使用 QwQ 32B）	88.1	92.0	86.3	51.5	8.2
DeepSeek R1 Llama	83.1	82.0	84.0	47.3	14.6
CePO（使用 DeepSeek R1 Llama）	90.2	84.0	89.4	47.2	15.5

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

模型	分数
o1-mini	56.67
coc-claude-3-5-sonnet-20241022	46.67
coc-gemini/gemini-exp-1121	46.67
o1-preview	40.00
gemini-exp-1114	36.67
claude-3-5-sonnet-20241022	20.00
gemini-1.5-pro-002	20.00
gemini-1.5-flash-002	16.67

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

模型	准确率
readurls&memory-gpt-4o-mini	61.29
gpt-4o-mini	50.61
readurls&memory-Gemma2-9b	30.1
Gemma2-9b	5.1
Gemma2-27b	30.8
Gemini Flash 1.5	66.5
Gemini Pro 1.5	72.9

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

模型	pass@1	pass@5	pass@10
plansearch-gpt-4o-mini	44.03	59.31	63.5
gpt-4o-mini	43.9	50.61	53.25
claude-3.5-sonnet	51.3
gpt-4o-2024-05-13	45.2
gpt-4-turbo-2024-04-09	44.2

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

optillm 与 Patchwork 结合使用（2024年7月）

由于 optillm 是 OpenAI API 的直接替代品，您可以使用 OpenAI 客户端轻松将其集成到现有工具和框架中。我们使用 optillm 与 patchwork 结合，这是一个开源框架，可通过称为 patchflows 的工作流自动执行开发中的重复性任务，如 PR 审查、错误修复和安全补丁。正如下面所示，当我们采用混合代理方法（moa）时，所有支持的 patchflows 都实现了巨大的性能提升。

测试

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

运行测试

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

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

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

# 运行单个测试
python tests/test.py --single-test "简单数学问题"

单元测试和集成测试

tests/ 目录中还提供了其他测试：

# 运行所有测试（需要 pytest）
./tests/run_tests.sh

# 运行特定的测试模块
pytest tests/test_plugins.py -v
pytest tests/test_api_compatibility.py -v

CI/CD

所有测试都会通过 GitHub Actions 在拉取请求上自动运行。工作流会测试：

• 多个 Python 版本（3.10、3.11、3.12）
• 插件和核心功能的单元测试
• API 兼容性测试
• 使用多种方法的集成测试

更多关于测试结构以及如何编写新测试的信息，请参阅 tests/README.md。

🤝 贡献

我们非常欢迎贡献！OptiLLM 是由社区共建、服务于社区的项目。

• 🐛 发现 bug？ 提交 issue
• 💡 有想法？ 发起讨论
• 🔧 想参与开发？ 查看 适合初学者的问题

开发环境搭建

git clone https://github.com/algorithmicsuperintelligence/optillm.git
cd optillm
python -m venv .venv
source .venv/bin/activate  # 或者在 Windows 上使用 `.venv\Scripts\activate`
pip install -r requirements.txt
pip install -r tests/requirements.txt

# 运行测试
python -m pytest tests/

参考文献

• 通过推理时技术激发微调 Transformer 的能力
• AutoThink：用于推理型 LLM 的高效推理 - 实现
• 深度思考，充满信心：基于置信度的推理与推理时缩放 - 实现
• 自我发现：大型语言模型自动生成推理结构 - 实现
• CePO：利用推理时计算赋能 Llama 模型进行推理 - 实现
• LongCePO：赋能 LLM 高效利用无限上下文 - 实现
• 代码链：结合语言模型增强的代码模拟器进行推理 - 启发了 coc 插件的实现
• 基于熵的采样与并行 CoT 解码 - 实现
• 事实、获取与推理：检索增强生成的统一评估 - 评估脚本
• 在边缘书写：适用于长上下文检索的更好推理模式 - 启发了 memory 插件的实现
• 无需提示的思维链推理 - 实现
• 重读提升大型语言模型的推理能力 - 实现
• 基于错误的上下文原则学习 - 实现
• 自然语言规划提升 LLM 的代码生成搜索能力 - 实现
• 自我一致性提升语言模型中的思维链推理 - 实现
• 互惠式推理使小型 LLM 成为更强大的问题解决者 - 实现
• 混合代理增强大型语言模型的能力 - 启发了 moa 插件的实现
• 证明者-验证者游戏提升 LLM 输出的可读性 - 实现
• 蒙特卡洛树搜索通过迭代偏好学习提升推理能力 - 启发了 mcts 插件的实现
• 使用往返正确性对代码 LLM 进行无监督评估 - 启发了 rto 插件的实现
• 改进的 MOA：优化针对多样化软件开发任务的推理 - 实现
• 改进的 RTC：评估 LLM 在多样化软件开发任务中的表现 - 实现
• AIMO-2 冠军方案：利用 OpenMathReasoning 数据集构建最先进的数学推理模型 - 实现
• 推理时扩散深度研究员 (TTD-DR)：多思考、多研究、回答更出色！ - 实现

引用

如果您在研究中使用此库，请引用以下内容：

@software{optillm,
  title = {OptiLLM：优化 LLM 推理的代理},
  author = {Asankhaya Sharma},
  year = {2024},
  publisher = {GitHub},
  url = {https://github.com/algorithmicsuperintelligence/optillm}
}

---

准备好优化您的 LLM 了吗？安装 OptiLLM，感受其中的不同吧！🚀

⭐ 如果您觉得 OptiLLM 很有用，请在 GitHub 上 [给它点个赞](https://github.com/algorithmicsuperintelligence/optillm)！

OptiLLM 快速上手指南

OptiLLM 是一个兼容 OpenAI API 的推理优化代理，无需训练或微调模型，即可通过 20+ 种前沿技术（如 MCTS、多智能体协作等）将大模型在数学、编程和逻辑推理任务上的准确率提升 2-10 倍。

环境准备

• 系统要求：支持 Linux、macOS 或 Windows（需安装 Python 环境）。
• 前置依赖：
  • Python 3.8+
  • pip 包管理工具
  • （可选）Docker：若选择容器化部署
• API Key：需要拥有任意 OpenAI 兼容接口的 API Key（如 OpenAI, Anthropic, Google, Cerebras 等）。

安装步骤

你可以选择通过 pip 直接安装或使用 Docker 部署。

方式一：使用 pip 安装（推荐）

# 安装 OptiLLM
pip install optillm

# 设置你的 API Key
export OPENAI_API_KEY="your-key-here"

# 启动服务
optillm

提示：国内用户若下载缓慢，可尝试使用清华源：pip install optillm -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：使用 Docker 部署

# 拉取最新镜像
docker pull ghcr.io/algorithmicsuperintelligence/optillm:latest

# 运行容器（映射端口 8000 并传入 API Key）
docker run -p 8000:8000 -e OPENAI_API_KEY="your-key-here" ghcr.io/algorithmicsuperintelligence/optillm:latest

基本使用

OptiLLM 启动后会在本地 http://localhost:8000/v1 提供一个兼容 OpenAI 的接口。你只需更改客户端的 base_url 和 model 名称即可启用优化策略。

1. 配置客户端

将 OpenAI 客户端的基础 URL 指向本地 OptiLLM 服务：

from openai import OpenAI

# 指向本地 OptiLLM 服务
client = OpenAI(base_url="http://localhost:8000/v1")

2. 调用优化模型

在模型名称前添加特定的前缀来激活不同的优化技术。例如，使用 moa- 前缀开启“多智能体混合（Mixture of Agents）”模式，可用小模型获得大模型的效果。

response = client.chat.completions.create(
    # 使用 moa- 前缀激活多智能体优化，让小模型具备 GPT-4o 级别的推理能力
    model="moa-gpt-4o-mini",  
    messages=[
        {"role": "user", "content": "Solve: If 2x + 3 = 7, what is x?"}
    ]
)

print(response.choices[0].message.content)

常用优化前缀参考

前缀	对应技术	适用场景
moa-	Mixture of Agents	通用推理提升，综合多个模型意见
mars-	Multi-Agent Reasoning	复杂数学与逻辑推导
cepo-	Cerebras Planning	结合思维链与自我反思的综合规划
plansearch-	PlanSearch	分步规划解决复杂问题
cot_reflection-	CoT with Reflection	带自我反思的思维链

效果对比示例：

• 普通模式：直接回答 "x = 1" (错误) ❌
• OptiLLM 模式：逐步推导 "2x + 3 = 7 → 2x = 4 → x = 2" (正确) ✅