OpenEvolve 快速入門指南

從 git clone 到實際運行 —— 完整實戰教程

📋 目錄

1. 環境需求
2. 獲取源碼
3. 安裝配置
4. 運行示例
5. 查看結果
6. 問題排查
7. OAuth 認證設置
8. 進階使用
9. 常用命令速查
10. 資源鏈接
11. 總結

1. 環境需求

系統要求

• Python: >= 3.10
• Git: 最新版本
• 操作系統: Linux / macOS / Windows (WSL)

檢查環境

# 檢查 Python 版本
python --version
# 輸出示例: Python 3.11.11

# 檢查 pip
pip --version
# 輸出示例: pip 25.3

# 檢查 Git
git --version
# 輸出示例: git version 2.x.x

2. 獲取源碼

克隆倉庫

# 克隆 OpenEvolve 項目
git clone https://github.com/google-deepmind/openevolve.git

# 進入項目目錄
cd openevolve

# 查看目錄結構
ls -la

目錄結構說明

openevolve/
├── openevolve/           # 核心源碼
│   ├── controller.py     # 主控制器
│   ├── database.py       # MAP-Elites 數據庫
│   ├── evaluator.py      # 程序評估器
│   └── llm/             # LLM 集成模組
├── examples/            # 示例項目（19個）
│   ├── function_minimization/  # 函數最小化示例
│   ├── sorting/         # 排序算法
│   ├── tsp/            # 旅行商問題
│   └── ...
├── tests/              # 單元測試
├── scripts/            # 工具腳本
├── Makefile           # 自動化構建
├── pyproject.toml     # 項目配置
└── README.md          # 項目說明

3. 安裝配置

方法一：使用 pip 安裝（推薦）

# 安裝 OpenEvolve（開發模式）
pip install -e .

# 驗證安裝
pip show openevolve

輸出示例：

Name: openevolve
Version: 0.2.26
Summary: Open-source implementation of AlphaEvolve
Location: /path/to/openevolve
Requires: dacite, flask, numpy, openai, pyyaml, tqdm

方法二：使用 Makefile

# 創建虛擬環境並安裝
make install

# 查看所有可用命令
make help

可用命令：

Available targets:
  all              - Install dependencies and run unit tests
  venv             - Create a virtual environment
  install          - Install Python dependencies
  install-dev      - Install development dependencies
  lint             - Run Black code formatting
  test             - Run unit tests only
  test-all         - Run both unit and integration tests
  docker-build     - Build the Docker image
  visualizer       - Run the visualization script

配置 API 密鑰

OpenEvolve 支持多種 LLM 提供商：

Google Gemini（示例中使用）

export GEMINI_API_KEY="your-gemini-api-key"
# 或者
export OPENAI_API_KEY="your-gemini-api-key"  # Gemini 兼容 OpenAI 接口

OpenAI

export OPENAI_API_KEY="your-openai-api-key"

本地 LLM

# 使用 Ollama 或其他本地模型
export OPENAI_API_BASE="http://localhost:11434/v1"
export OPENAI_API_KEY="ollama"

4. 運行示例

示例：函數最小化（Function Minimization）

這是最簡單的入門示例，展示如何將隨機搜尋算法演化為模擬退火算法。

4.1 進入示例目錄

cd examples/function_minimization

4.2 查看示例文件

ls -la

文件說明：

function_minimization/
├── initial_program.py   # 初始程序（隨機搜尋）
├── evaluator.py         # 評估器（測試程序性能）
├── config.yaml         # 配置文件（LLM、迭代次數等）
├── README.md           # 示例說明
└── requirements.txt    # 依賴

4.3 檢查配置文件

cat config.yaml

關鍵配置：

max_iterations: 10          # 最大迭代次數
checkpoint_interval: 5      # 每5次迭代保存checkpoint

# LLM 配置
llm:
  primary_model: "gemini-2.5-flash-lite"
  primary_model_weight: 0.8
  secondary_model: "gemini-2.5-flash"
  secondary_model_weight: 0.2
  api_base: "https://generativelanguage.googleapis.com/v1beta/openai/"
  temperature: 0.7
  max_tokens: 16000
  timeout: 120

# 數據庫配置（MAP-Elites）
database:
  population_size: 50
  archive_size: 20
  num_islands: 3            # 3個隔離的演化種群
  elite_selection_ratio: 0.2
  exploitation_ratio: 0.7

4.4 運行演化

完整運行（10次迭代）：

python ../../openevolve-run.py \
  initial_program.py \
  evaluator.py \
  --config config.yaml \
  --iterations 10

快速測試（5次迭代）：

OPENAI_API_KEY=$GEMINI_API_KEY python ../../openevolve-run.py \
  initial_program.py \
  evaluator.py \
  --config config.yaml \
  --iterations 5

運行輸出示例：

2026-02-02 22:42:01,252 - INFO - Logging to openevolve_output/logs/openevolve_20260202_224201.log
2026-02-02 22:42:01,255 - INFO - Set random seed to 42 for reproducibility
2026-02-02 22:42:01,323 - INFO - Initialized OpenAI LLM with model: gemini-2.5-flash-lite
2026-02-02 22:42:01,334 - INFO - Initialized LLM ensemble with models: gemini-2.5-flash-lite (weight: 0.80), gemini-2.5-flash (weight: 0.20)
2026-02-02 22:42:01,358 - INFO - Initialized program database with 0 programs
2026-02-02 22:42:01,364 - INFO - Evaluated program 022cc7dc in 0.00s: runs_successfully=1.0000, combined_score=1.2148
2026-02-02 22:42:01,365 - INFO - Starting process-based evolution from iteration 1 for 5 iterations
...
2026-02-02 22:42:58,232 - INFO - Evolution complete. Best program has metrics:
    runs_successfully=1.0000,
    value_score=0.9418,
    distance_score=0.7566,
    combined_score=1.2148

4.5 恢復訓練（Resume）

# 從 checkpoint 恢復
python ../../openevolve-run.py \
  initial_program.py \
  evaluator.py \
  --config config.yaml \
  --checkpoint openevolve_output/checkpoints/checkpoint_5 \
  --iterations 50

5. 查看結果

5.1 輸出目錄結構

tree openevolve_output/

目錄結構：

openevolve_output/
├── best/                          # 最優程序
│   ├── best_program.py           # 最佳代碼
│   └── best_program_info.json    # 性能指標
├── checkpoints/                   # 檢查點
│   └── checkpoint_5/
│       ├── best_program.py
│       ├── best_program_info.json
│       ├── metadata.json          # 演化元數據
│       └── programs/              # 所有程序快照
└── logs/                          # 運行日誌
    └── openevolve_20260202_224201.log

5.2 查看最佳程序

cat openevolve_output/best/best_program.py

初始程序（隨機搜尋）：

def search_algorithm(iterations=1000, bounds=(-5, 5)):
    """簡單的隨機搜尋算法，容易陷入局部最優"""
    best_x = np.random.uniform(bounds[0], bounds[1])
    best_y = np.random.uniform(bounds[0], bounds[1])
    best_value = evaluate_function(best_x, best_y)

    for _ in range(iterations):
        x = np.random.uniform(bounds[0], bounds[1])
        y = np.random.uniform(bounds[0], bounds[1])
        value = evaluate_function(x, y)

        if value < best_value:
            best_value = value
            best_x, best_y = x, y

    return best_x, best_y, best_value

演化後的程序（模擬退火）：

def search_algorithm(iterations=1000, bounds=(-5, 5)):
    """改進的模擬退火算法，能夠跳出局部最優"""
    # 初始化
    current_x = np.random.uniform(bounds[0], bounds[1])
    current_y = np.random.uniform(bounds[0], bounds[1])
    current_value = evaluate_function(current_x, current_y)

    best_x, best_y, best_value = current_x, current_y, current_value

    # 模擬退火參數
    T = 1.0  # 初始溫度
    T_min = 0.001
    alpha = 0.995  # 冷卻係數

    for i in range(iterations):
        # 在當前點附近生成新候選點
        step_size = T * (bounds[1] - bounds[0]) / 10
        new_x = np.clip(current_x + np.random.uniform(-step_size, step_size),
                        bounds[0], bounds[1])
        new_y = np.clip(current_y + np.random.uniform(-step_size, step_size),
                        bounds[0], bounds[1])
        new_value = evaluate_function(new_x, new_y)

        # Metropolis準則：決定是否接受新解
        if new_value < current_value:
            current_x, current_y, current_value = new_x, new_y, new_value
            if new_value < best_value:
                best_x, best_y, best_value = new_x, new_y, new_value
        else:
            # 以一定概率接受更差的解（跳出局部最優）
            if np.random.random() < np.exp(-(new_value - current_value) / T):
                current_x, current_y, current_value = new_x, new_y, new_value

        # 降溫
        T = max(T * alpha, T_min)

    return best_x, best_y, best_value

5.3 查看性能指標

cat openevolve_output/best/best_program_info.json

性能對比：

{
  "metrics": {
    "runs_successfully": 1.0,
    "value_score": 0.9418,       // 找到的最小值（越接近0越好）
    "distance_score": 0.7566,    // 與全局最優的距離
    "combined_score": 1.2148     // 綜合評分
  },
  "features": {
    "complexity": 5,              // 代碼複雜度
    "diversity": 0               // 多樣性得分
  },
  "improvement": "3.9x faster"   // 相比初始程序的提升
}

5.4 可視化演化樹

# 使用 visualizer 查看演化過程
python ../../scripts/visualizer.py --path openevolve_output/checkpoints/checkpoint_5/

6. 問題排查

問題 1: API Key 錯誤

Error: The api_key client option must be set

解決方法：

# 確保設置了 API key
echo $GEMINI_API_KEY    # 或 $OPENAI_API_KEY

# 如果未設置
export OPENAI_API_KEY="your-api-key"

# 或在運行時指定
OPENAI_API_KEY="xxx" python openevolve-run.py ...

問題 2: API 配額限制

Error code: 429 - Quota exceeded for quota metric 'Generate Content API requests per minute'

解決方法：

1. 等待配額重置（通常1分鐘）
2. 減少並行度：

   # config.yaml
   evaluator:
     parallel_evaluations: 1  # 從3改為1
   

3. 使用不同的模型：

   llm:
     primary_model: "gemini-2.0-flash-lite"  # 更經濟的模型
   

4. 使用 OAuth 認證：參考第7章 OAuth 認證設置

問題 3: 依賴缺失

ModuleNotFoundError: No module named 'openevolve'

解決方法：

# 重新安裝
pip install -e .

# 或使用 Makefile
make install

問題 4: Python 版本過低

ERROR: This package requires Python >=3.10

解決方法：

# 使用 conda 創建新環境
conda create -n openevolve python=3.11
conda activate openevolve

# 或使用 pyenv
pyenv install 3.11.0
pyenv local 3.11.0

問題 5: 權限錯誤

Permission denied: 'openevolve_output/'

解決方法：

# 檢查目錄權限
ls -la

# 修復權限
chmod -R u+w openevolve_output/

# 或刪除並重新運行
rm -rf openevolve_output/

7. OAuth 認證設置

解決 API 配額限制問題 - 使用 OAuth 2.0 獲得更高配額

7.1 為什麼使用 OAuth？

問題：API Key 配額限制

目前遇到的錯誤：

Error code: 429 - Quota exceeded for quota metric 'Generate Content API requests per minute'
quota_limit_value: '0'  # 免費配額已用盡

解決方案：OAuth 認證

OAuth 認證提供：

• ✅ 更高的配額：通常比 API Key 高 10-100 倍
• ✅ 用戶級別的配額：不是全局共享配額
• ✅ 更好的控制：可以在 Google Cloud Console 中管理配額
• ✅ 生產級別：適合正式應用

7.2 OAuth vs API Key 對比

7.3 設置步驟

步驟 1: 創建 Google Cloud 項目

# 1. 訪問 Google Cloud Console
open https://console.cloud.google.com/

# 2. 創建新項目（或選擇現有項目）
# 項目名稱: openevolve-oauth

步驟 2: 啟用 Gemini API

# 1. 進入 API 庫
https://console.cloud.google.com/apis/library

# 2. 搜尋並啟用：
# - Generative Language API
# - Cloud Resource Manager API（如需要）

# 或使用 gcloud 命令
gcloud services enable generativelanguage.googleapis.com

步驟 3: 配置 OAuth 同意屏幕

1. 進入 OAuth 同意屏幕設置：

   https://console.cloud.google.com/apis/credentials/consent
   

2. 選擇用戶類型：

   • 外部（External）：適合測試和個人使用
   • 點擊「創建」

3. 填寫應用信息：

   應用名稱: OpenEvolve
   用戶支持郵箱: your-email@example.com
   開發者聯繫信息: your-email@example.com
   

4. 添加範圍（Scopes）：

   https://www.googleapis.com/auth/generative-language.retriever
   https://www.googleapis.com/auth/cloud-platform
   

5. 添加測試用戶：

   • 添加你的 Google 帳號郵箱

步驟 4: 創建 OAuth 2.0 憑證

1. 進入憑證頁面：

   https://console.cloud.google.com/apis/credentials
   

2. 創建憑證 → OAuth 2.0 客戶端 ID

3. 選擇應用類型：

   • 桌面應用（Desktop Application）

4. 命名：

   名稱: OpenEvolve Desktop Client
   

5. 下載憑證：

   • 點擊「下載 JSON」
   • 保存為 client_secret.json

步驟 5: 使用 gcloud 認證

# 1. 安裝 gcloud CLI（如果還沒有）
# macOS/Linux
curl https://sdk.cloud.google.com | bash

# 或訪問：https://cloud.google.com/sdk/docs/install

# 2. 初始化 gcloud
gcloud init

# 3. 設置應用默認憑證
gcloud auth application-default login

# 4. 設置項目
gcloud config set project YOUR_PROJECT_ID

# 5. 獲取 access token（測試用）
gcloud auth application-default print-access-token

成功輸出：

ya29.a0AfH6SMBx... （一個很長的 token）

步驟 6: 設置環境變量

# 方法 1: 使用 access token（短期有效，約1小時）
export GEMINI_ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
export OPENAI_API_KEY=$GEMINI_ACCESS_TOKEN

# 方法 2: 使用憑證文件（推薦）
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/client_secret.json"

7.4 在 OpenEvolve 中使用

方法 A: 使用 Access Token（簡單但需定期刷新）

# 1. 獲取 token
export ACCESS_TOKEN=$(gcloud auth application-default print-access-token)

# 2. 運行 OpenEvolve
cd examples/function_minimization
OPENAI_API_KEY=$ACCESS_TOKEN python ../../openevolve-run.py \
  initial_program.py evaluator.py \
  --config config.yaml \
  --iterations 10

注意：Access token 通常 1 小時後過期，需要重新獲取。

方法 B: 自動刷新 Token 腳本

# 創建自動刷新腳本
cat > run_with_oauth.sh << 'EOF'
#!/bin/bash

cd examples/function_minimization

while true; do
    # 獲取新 token
    export OPENAI_API_KEY=$(gcloud auth application-default print-access-token)
    echo "🔄 Token 已刷新：$(date)"

    # 運行 OpenEvolve（運行完成或1小時後自動重啟）
    timeout 3300 python ../../openevolve-run.py \
        initial_program.py evaluator.py \
        --config config.yaml \
        --iterations 10 && break

    # 如果運行中斷，等待後重試
    echo "⏳ 等待 5 秒後重試..."
    sleep 5
done

echo "✅ 演化完成！"
EOF

chmod +x run_with_oauth.sh
./run_with_oauth.sh

方法 C: 使用 Google AI Python SDK（最佳方案）

# 1. 安裝 Google AI SDK
pip install google-generativeai google-auth

# 2. 創建認證腳本
cat > run_with_oauth.py << 'EOF'
import os
import sys
import google.generativeai as genai
from google.auth.transport.requests import Request
import google.auth

# 獲取 OAuth credentials
credentials, project = google.auth.default(
    scopes=['https://www.googleapis.com/auth/generative-language.retriever']
)

if not credentials.valid:
    if credentials.expired and credentials.refresh_token:
        credentials.refresh(Request())

# 設置環境變量
os.environ['OPENAI_API_KEY'] = credentials.token

# 運行 OpenEvolve
import subprocess
result = subprocess.run([
    sys.executable, '../../openevolve-run.py',
    'initial_program.py', 'evaluator.py',
    '--config', 'config.yaml',
    '--iterations', '10'
])

sys.exit(result.returncode)
EOF

# 3. 運行
python run_with_oauth.py

7.5 配額對比

7.6 快速開始（推薦流程）

# 1. 安裝 gcloud CLI
curl https://sdk.cloud.google.com | bash
exec -l $SHELL

# 2. 初始化並登入
gcloud init
gcloud auth application-default login

# 3. 啟用 API
gcloud services enable generativelanguage.googleapis.com

# 4. 設置項目
export PROJECT_ID="your-project-id"
gcloud config set project $PROJECT_ID

# 5. 獲取 token 並運行
cd examples/function_minimization
export OPENAI_API_KEY=$(gcloud auth application-default print-access-token)
python ../../openevolve-run.py \
  initial_program.py evaluator.py \
  --config config.yaml \
  --iterations 10

echo "✅ OAuth 認證設置完成！"

7.7 常見問題

Q1: Token 過期怎麼辦？

A: Access token 通常 1 小時後過期。解決方案：

# 方法 1: 定期手動刷新
export OPENAI_API_KEY=$(gcloud auth application-default print-access-token)

# 方法 2: 使用自動刷新腳本（參考 7.4 方法 B）

Q2: 配額還是不夠怎麼辦？

A: 申請配額提升

1. 訪問配額頁面：

   https://console.cloud.google.com/apis/api/generativelanguage.googleapis.com/quotas
   

2. 選擇要提升的配額：

   • Requests per minute per project
   • Tokens per minute per project

3. 點擊「申請配額提升」

4. 填寫申請表單：

   • 說明用途：學術研究 / 開發測試
   • 預計請求量：每分鐘 60 次
   • 理由：進行算法優化實驗

Q3: OAuth 設置太複雜，有簡單方案嗎？

A: 使用 Service Account（服務帳號）

# 1. 創建 Service Account
gcloud iam service-accounts create openevolve-sa \
    --display-name="OpenEvolve Service Account"

# 2. 授權
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
    --member="serviceAccount:openevolve-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

# 3. 創建密鑰
gcloud iam service-accounts keys create ~/openevolve-key.json \
    --iam-account=openevolve-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com

# 4. 設置環境變量
export GOOGLE_APPLICATION_CREDENTIALS=~/openevolve-key.json

Q4: 如何檢查配額使用情況？

A: 使用 Google Cloud Console

# 1. 訪問配額頁面
https://console.cloud.google.com/apis/api/generativelanguage.googleapis.com/quotas

# 2. 查看當前配額：
# - Requests per minute per user
# - Requests per day per project
# - Tokens per minute

# 3. 或使用 gcloud 命令
gcloud services quota list \
    --service=generativelanguage.googleapis.com \
    --consumer=projects/YOUR_PROJECT_ID

Q5: 為什麼我的配額是 0？

A: 這通常是因為：

1. 地區限制：asia-east1 地區的免費配額可能為 0

   • 解決：切換到 us-central1 或其他地區

2. API 未啟用：

   • 解決：確保已啟用 Generative Language API

3. 免費層限制：

   • 解決：升級到付費帳號或申請配額提升

4. 未使用 OAuth：

   • 解決：改用 OAuth 認證（本章節的方法）

8. 進階使用

8.1 自定義配置

修改迭代次數

# config.yaml
max_iterations: 50          # 增加到50次迭代
checkpoint_interval: 10     # 每10次保存

切換 LLM 模型

# 使用 OpenAI
llm:
  primary_model: "gpt-5-mini"
  api_base: "https://api.openai.com/v1"

# 使用本地模型（Ollama）
llm:
  primary_model: "llama3.1-8b"
  api_base: "http://localhost:11434/v1"

調整演化策略

# 差異演化 vs 完全重寫
diff_based_evolution: true   # true=差異演化，false=完全重寫

# 數據庫參數
database:
  population_size: 100       # 增加種群規模
  num_islands: 5            # 增加島嶼數量（更多樣性）
  exploitation_ratio: 0.8   # 增加開發比例（更少探索）

8.2 使用其他示例

排序算法優化

cd examples/sorting
python ../../openevolve-run.py initial_program.py evaluator.py --config config.yaml --iterations 20

旅行商問題（TSP）

cd examples/tsp
python ../../openevolve-run.py initial_program.py evaluator.py --config config.yaml --iterations 30

ARC-AGI 挑戰

cd examples/arc-agi
python ../../openevolve-run.py initial_program.py evaluator.py --config config.yaml --iterations 100

8.3 Library API 使用

在 Python 代碼中直接使用 OpenEvolve：

from openevolve import OpenEvolve

# 創建配置
config = {
    'llm': {
        'primary_model': 'gemini-2.5-flash-lite',
        'api_base': 'https://generativelanguage.googleapis.com/v1beta/openai/',
        'temperature': 0.7
    },
    'max_iterations': 10,
    'database': {
        'population_size': 50,
        'num_islands': 3
    }
}

# 初始化 OpenEvolve
oe = OpenEvolve(
    initial_program='path/to/initial_program.py',
    evaluator='path/to/evaluator.py',
    config=config
)

# 運行演化
oe.run()

# 獲取最佳程序
best_program = oe.get_best_program()
print(f"Best score: {best_program.metrics['combined_score']}")

8.4 Docker 運行

# 構建鏡像
make docker-build

# 運行示例
make docker-run

9. 常用命令速查

# 安裝
pip install -e .

# 運行示例
cd examples/function_minimization
python ../../openevolve-run.py initial_program.py evaluator.py --config config.yaml --iterations 10

# 使用 OAuth 運行
export OPENAI_API_KEY=$(gcloud auth application-default print-access-token)
python ../../openevolve-run.py initial_program.py evaluator.py --config config.yaml --iterations 10

# 恢復訓練
python ../../openevolve-run.py initial_program.py evaluator.py --checkpoint openevolve_output/checkpoints/checkpoint_5 --iterations 50

# 可視化
python ../../scripts/visualizer.py --path openevolve_output/checkpoints/checkpoint_5/

# 運行測試
make test

# 格式化代碼
make lint

# 查看幫助
python ../../openevolve-run.py --help

10. 資源鏈接

• GitHub 倉庫: https://github.com/google-deepmind/openevolve
• 論文: AlphaEvolve: Improving Algorithms with Large Language Models
• 文檔: https://openevolve.readthedocs.io/
• 示例合集: /examples/ 目錄
• 常見問題: https://github.com/google-deepmind/openevolve/issues
• OAuth 文檔: https://ai.google.dev/gemini-api/docs/oauth
• Google Cloud Console: https://console.cloud.google.com/
• 配額管理: https://console.cloud.google.com/apis/api/generativelanguage.googleapis.com/quotas

11. 總結

關鍵要點

1. 環境準備: Python >= 3.10 + API Key (或 OAuth)
2. 安裝簡單: pip install -e . 一鍵安裝
3. 配置靈活: 支持多種 LLM（Gemini/OpenAI/本地）
4. 認證方式: API Key（快速測試）或 OAuth（生產環境）
5. 示例豐富: 19個實際應用場景
6. 結果可視化: 自帶演化樹可視化工具

工作流程

1. 準備初始程序（initial_program.py）
2. 編寫評估器（evaluator.py）
3. 配置 LLM 和參數（config.yaml）
4. 設置認證（API Key 或 OAuth）
5. 運行演化（openevolve-run.py）
6. 查看結果（best_program.py）
7. 可視化分析（visualizer.py）

性能提升

在 function_minimization 示例中：

• 初始算法: 隨機搜尋，容易陷入局部最優
• 演化結果: 模擬退火算法，全局搜尋能力強
• 性能提升: 約 3.9倍

配額管理建議

• 開發測試: 使用 API Key 快速開始
• 遇到配額限制: 切換到 OAuth 認證
• 生產環境: 申請配額提升或使用付費方案
• 離線開發: 使用本地 LLM (Ollama)

祝你使用愉快！🚀

如有問題，請在 GitHub Issues 提出。