feat: implement true OPRO with Gemini-style UI

- Add true OPRO system instruction optimization (vs query rewriting) - Implement iterative optimization with performance trajectory - Add new OPRO API endpoints (/opro/create, /opro/generate_and_evaluate, /opro/execute) - Create modern Gemini-style chat UI (frontend/opro.html) - Optimize performance: reduce candidates from 20 to 10 (2x faster) - Add model selector in UI toolbar - Add collapsible sidebar with session management - Add copy button for instructions - Ensure all generated prompts use simplified Chinese - Update README with comprehensive documentation - Add .gitignore for local_docs folder
2025-12-06 17:24:28 +08:00
parent 8f52fad41c
commit 1376d60ed5
10 changed files with 1817 additions and 13 deletions
--- a/README.md
+++ b/README.md
@@ -1,3 +1,218 @@
+# 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 服务
+
+### 安装依赖
+
+```bash
+# 创建 conda 环境（推荐）
+conda create -n opro python=3.10
+conda activate opro
+
+# 安装 Python 依赖
+pip install fastapi uvicorn requests numpy scikit-learn pydantic
+```
+
+### 启动 Ollama 服务
+
+```bash
+# 确保 Ollama 已安装并运行
+ollama serve
+
+# 拉取所需模型
+ollama pull qwen3:8b
+ollama pull qwen3-embedding:4b
+```
+
+### 启动应用
+
+```bash
+# 启动后端服务
+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`
+
+### 关键配置项
+
+```python
+# 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 服务正在运行：
+```bash
+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`
+
+---
+
+<details>
+<summary><b>原始 README（点击展开）</b></summary>
+
 - 项目简介

 - OPRO Prompt Optimizer：面向提示优化的交互式系统，支持多轮拒选/再生成、语义聚类去重与 Top‑K 代表选择。
@@ -64,4 +279,6 @@
 - 模型不可用： /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
+- 端口与地址访问差异：在启动命令中明确 --host 0.0.0.0 --port 8010 ，本地浏览器建议访问 127.0.0.1
+
+</details>