OPRO Prompt Optimizer

功能概述

OPRO (Optimization by PROmpting) 是一个基于大语言模型的提示词优化系统。本项目实现了真正的 OPRO 算法，通过迭代优化系统指令（System Instructions）来提升 LLM 在特定任务上的性能。

核心功能

• 系统指令优化：使用 LLM 作为优化器，基于历史性能轨迹生成更优的系统指令
• 多轮迭代优化：支持多轮优化，每轮基于前一轮的性能反馈生成新的候选指令
• 智能候选选择：通过语义聚类和多样性选择，从大量候选中筛选出最具代表性的指令
• 性能评估：支持自定义测试用例对系统指令进行自动评估
• 会话管理：支持多个优化任务的并行管理和历史记录

用户界面

• 现代化聊天界面：类似 Google Gemini 的简洁设计
• 侧边栏会话管理：可折叠的侧边栏，支持多会话切换
• 实时优化反馈：每轮优化生成 3-5 个候选指令，用户可选择继续优化或执行
• 模型选择：支持在界面中选择不同的 LLM 模型

主要优化改进

1. 真正的 OPRO 实现

原始代码实现的是查询重写（Query Rewriting），而非真正的 OPRO。我们添加了完整的 OPRO 功能：

• 系统指令生成：generate_system_instruction_candidates() - 生成多样化的系统指令候选
• 性能评估：evaluate_system_instruction() - 基于测试用例评估指令性能
• 轨迹优化：基于历史 (instruction, score) 轨迹生成更优指令
• 元提示工程：专门设计的元提示用于指导 LLM 生成和优化系统指令

2. 性能优化

• 候选池大小优化：从 20 个候选减少到 10 个，速度提升约 2 倍
• 智能聚类选择：使用 AgglomerativeClustering 从候选池中选择最具多样性的 Top-K
• 嵌入服务回退：Xinference → Ollama 自动回退机制，确保服务可用性

3. API 架构改进

• 新增 OPRO 端点：
  • POST /opro/create - 创建 OPRO 优化任务
  • POST /opro/generate_and_evaluate - 生成并自动评估候选
  • POST /opro/execute - 执行系统指令
  • GET /opro/runs - 获取所有优化任务
  • GET /opro/run/{run_id} - 获取特定任务详情
• 会话状态管理：完整的 OPRO 运行状态跟踪（轨迹、测试用例、迭代次数）
• 向后兼容：保留原有查询重写功能，标记为 opro-legacy

4. 前端界面重构

• Gemini 风格设计：简洁的白色/灰色配色，圆角设计，微妙的阴影效果
• 可折叠侧边栏：默认折叠，支持会话列表管理
• 多行输入框：支持多行文本输入，底部工具栏包含模型选择器
• 候选指令卡片：每个候选显示编号、内容、分数，提供"继续优化"、"复制"、"执行"按钮
• 简体中文界面：所有 UI 文本和生成的指令均使用简体中文

快速开始

环境要求

• Python ≥ 3.10（推荐使用 conda 虚拟环境）
• Ollama 本地服务及模型（如 qwen3:8b、qwen3-embedding:4b）
• 可选：Xinference embedding 服务

安装依赖

# 创建 conda 环境（推荐）
conda create -n opro python=3.10
conda activate opro

# 安装 Python 依赖
pip install fastapi uvicorn requests numpy scikit-learn pydantic

启动 Ollama 服务

# 确保 Ollama 已安装并运行
ollama serve

# 拉取所需模型
ollama pull qwen3:8b
ollama pull qwen3-embedding:4b

启动应用

# 启动后端服务
uvicorn _qwen_xinference_demo.api:app --host 127.0.0.1 --port 8010

# 或使用 0.0.0.0 允许外部访问
uvicorn _qwen_xinference_demo.api:app --host 0.0.0.0 --port 8010

访问界面

• OPRO 优化界面：http://127.0.0.1:8010/ui/opro.html
• 传统三栏界面：http://127.0.0.1:8010/ui/
• API 文档：http://127.0.0.1:8010/docs
• OpenAPI JSON：http://127.0.0.1:8010/openapi.json

使用示例

1. 创建新会话：在 OPRO 界面点击"新建会话"或侧边栏的 + 按钮
2. 输入任务描述：例如"将中文翻译成英文"
3. 查看候选指令：系统生成 3-5 个优化的系统指令
4. 继续优化：点击"继续优化"进行下一轮迭代
5. 执行指令：点击"执行此指令"测试指令效果
6. 复制指令：点击"复制"按钮将指令复制到剪贴板

配置说明

配置文件：config.py

关键配置项

# Ollama 服务配置
OLLAMA_HOST = "http://127.0.0.1:11434"
DEFAULT_CHAT_MODEL = "qwen3:8b"
DEFAULT_EMBED_MODEL = "qwen3-embedding:4b"

# OPRO 优化参数
GENERATION_POOL_SIZE = 10  # 生成候选池大小
TOP_K = 5                   # 返回给用户的候选数量
CLUSTER_DISTANCE_THRESHOLD = 0.15  # 聚类距离阈值

# Xinference 配置（可选）
XINFERENCE_EMBED_URL = "http://127.0.0.1:9997/models/bge-base-zh/embed"

项目结构

.
├── _qwen_xinference_demo/
│   ├── api.py                          # FastAPI 主应用
│   └── opro/
│       ├── user_prompt_optimizer.py    # OPRO 核心逻辑
│       ├── prompt_utils.py             # 元提示生成
│       ├── session_state.py            # 会话状态管理
│       ├── ollama_client.py            # Ollama 客户端
│       └── xinference_client.py        # Xinference 客户端
├── frontend/
│   ├── opro.html                       # OPRO 优化界面
│   └── index.html                      # 传统三栏界面
├── examples/
│   ├── opro_demo.py                    # OPRO 功能演示
│   └── client_demo.py                  # API 调用示例
├── config.py                           # 全局配置
├── API.md                              # API 文档
└── README.md                           # 本文件

API 端点

OPRO 相关（推荐使用）

• POST /opro/create - 创建优化任务
• POST /opro/generate_and_evaluate - 生成并评估候选
• POST /opro/execute - 执行系统指令
• GET /opro/runs - 获取所有任务
• GET /opro/run/{run_id} - 获取任务详情

传统端点（向后兼容）

• POST /query - 查询重写（首轮）
• POST /select - 选择候选并回答
• POST /reject - 拒绝并重新生成
• POST /message - 聊天消息

通用端点

• GET /health - 健康检查
• GET /version - 版本信息
• GET /models - 可用模型列表
• POST /set_model - 设置模型

详细 API 文档请访问：http://127.0.0.1:8010/docs

常见问题

1. 无法连接 Ollama 服务

确保 Ollama 服务正在运行：

ollama serve

检查配置文件中的 OLLAMA_HOST 是否正确。

2. 模型不可用

通过 /models 端点查看可用模型列表，使用 /set_model 切换模型。

3. 生成速度慢

• 调整 GENERATION_POOL_SIZE 减少候选数量
• 使用更小的模型（如 qwen3:4b）
• 确保 Ollama 使用 GPU 加速

4. 界面显示异常

硬刷新浏览器缓存：

• Mac: Cmd + Shift + R
• Windows/Linux: Ctrl + Shift + R

---

原始 README（点击展开）

• 项目简介

• OPRO Prompt Optimizer：面向提示优化的交互式系统，支持多轮拒选/再生成、语义聚类去重与 Top‑K 代表选择。

• 后端 FastAPI 提供 REST 接口，前端三栏 UI 便于会话管理与候选挑选。

• 架构概览

• Frontend /ui/ → POST /query 首轮候选 → POST /select 选择并回答 → POST /reject 再生成 → POST /query_from_message 基于最近消息优化 → POST /message 聊天

• OPRO 流程：指令构造 → Qwen 批量生成 → Embedding（Xinference→Ollama 回退）→ 聚类去重 → Top‑K

• 核心实现位置： _qwen_xinference_demo/opro/user_prompt_optimizer.py:45-54 （候选生成）、 _qwen_xinference_demo/opro/xinference_client.py:7-28 （embedding 回退）

• 环境与依赖

• Python ≥ 3.10（建议使用 conda 虚拟环境）

• 必需：Ollama 本地服务与模型（如 qwen3:8b ， qwen3-embedding:4b ）

• 可选：Xinference embedding 服务（ http://127.0.0.1:9997/models/bge-base-zh/embed ）

• Python 依赖： fastapi 、 uvicorn 、 requests 、 numpy 、 scikit-learn 、 pydantic

• 安装与启动

• 安装依赖

  • pip install fastapi uvicorn requests numpy scikit-learn pydantic

• 启动后端服务

  • uvicorn _qwen_xinference_demo.api:app --host 0.0.0.0 --port 8010

• 访问页面

  • 前端三栏 UI： http://127.0.0.1:8010/ui/
  • OpenAPI 文档： http://127.0.0.1:8010/docs
  • OpenAPI JSON： http://127.0.0.1:8010/openapi.json

• 配置

• 文件： config.py

• 关键项

  • APP_TITLE 、 APP_DESCRIPTION 、 APP_VERSION 、 APP_CONTACT （应用元信息，见 _qwen_xinference_demo/api.py:14-26 ）
  • OLLAMA_HOST 、 OLLAMA_GENERATE_URL 、 OLLAMA_TAGS_URL （Ollama 端点）
  • DEFAULT_CHAT_MODEL 、 DEFAULT_EMBED_MODEL （默认模型，用于 _qwen_xinference_demo/opro/ollama_client.py:4-7 与 _qwen_xinference_demo/opro/xinference_client.py:1-6,20-21 ）
  • XINFERENCE_EMBED_URL （优先 embedding 端点）
  • TOP_K 、 CLUSTER_DISTANCE_THRESHOLD （候选选择参数，引用 _qwen_xinference_demo/opro/user_prompt_optimizer.py:19,45 ）

• 统一响应与错误处理

• 成功： {"success": true, "data": {...}}

• 失败： {"success": false, "error": "...", "error_code": "..."} ，状态码保持 HTTP 值

• 应用级异常： AppException(status_code, detail, error_code) _qwen_xinference_demo/api.py:23-39

• 示例：会话不存在抛出 SESSION_NOT_FOUND ，Ollama 调用异常抛出 OLLAMA_ERROR

• API 与示例

• 全量端点与示例：见 API.md

• 健康与版本

  • GET /health 返回 {status, version} _qwen_xinference_demo/api.py:129-134
  • GET /version 返回 {version} _qwen_xinference_demo/api.py:135-138

• 示例脚本

  • 入口： examples/client_demo.py
  • 功能：健康检查 → 创建会话 → 选择候选 → 继续优化 → 聊天 → 会话列表

• 目录结构

• /_qwen_xinference_demo/api.py ：FastAPI 主应用与路由

• /_qwen_xinference_demo/opro/user_prompt_optimizer.py ：OPRO 候选生成与聚类选择

• /_qwen_xinference_demo/opro/xinference_client.py ：Embedding（Xinference→Ollama 回退）

• /_qwen_xinference_demo/opro/ollama_client.py ：Ollama 调用与模型列表

• /_qwen_xinference_demo/opro/session_state.py ：会话态管理

• /frontend/index.html ：三栏 UI 页面

• /API.md ：接口文档

• /examples/client_demo.py ：示例调用脚本

• /config.py ：全局配置

• 常见问题

• 无法访问 /ui/react ：使用 /ui/ ，React 示例仅作演示入口 _qwen_xinference_demo/api.py:133-144

• 模型不可用： /models 查看列表并通过 /set_model 应用；错误返回 MODEL_NOT_AVAILABLE

• 第二轮无相关候选：使用 POST /query_from_message 基于最近消息再生候选 _qwen_xinference_demo/api.py:193-206

• 立即回答诉求：用 POST /answer 先答后给候选 _qwen_xinference_demo/api.py:211-219

• 端口与地址访问差异：在启动命令中明确 --host 0.0.0.0 --port 8010 ，本地浏览器建议访问 127.0.0.1