opro_demo/README.md

# System Prompt Generator

## 功能概述

这是一个基于大语言模型的系统提示词（System Prompt）生成和迭代优化工具。通过简单的任务描述，自动生成高质量的系统指令，并支持基于用户选择的迭代改进。

### 核心功能

- **智能指令生成**：根据任务描述自动生成多个高质量的系统指令候选
- **迭代式改进**：基于用户选择的指令生成改进版本，避免被拒绝的方向
- **角色定义格式**：所有生成的指令都以角色定义开头（如"你是一个..."），符合最佳实践
- **智能候选选择**：通过语义聚类和多样性选择，从大量候选中筛选出最具代表性的指令
- **会话管理**：支持多个任务的并行管理和历史记录
- **全面覆盖要求**：生成的指令全面覆盖任务的所有要求和细节，而非仅追求风格多样性

### 用户界面

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

## 核心特性

### 1. 简单直观的工作流程

不同于复杂的 OPRO 算法（需要测试用例和自动评估），本工具采用简单直观的迭代改进方式：

- **初始生成**：输入任务描述 → 生成 5 个全面的系统指令候选
- **迭代改进**：选择喜欢的指令 → 生成基于该指令的改进版本，同时避免被拒绝的方向
- **无需评分**：不需要测试用例或性能评分，完全基于用户偏好进行改进

### 2. 高质量指令生成

- **角色定义格式**：所有指令以"你是一个..."开头，符合系统提示词最佳实践
- **全面覆盖要求**：生成的指令全面覆盖任务的所有要求和细节
- **清晰可执行**：指令清晰、具体、可执行，包含必要的行为规范和输出格式
- **简体中文**：所有生成的指令使用简体中文

### 3. 性能优化

- **候选池大小优化**：生成 10 个候选，通过聚类选择 5 个最具多样性的
- **智能聚类选择**：使用 AgglomerativeClustering 从候选池中选择最具代表性的指令
- **嵌入服务回退**：Xinference → Ollama 自动回退机制，确保服务可用性

### 4. API 架构

- **核心端点**：
  - `POST /opro/create` - 创建新任务
  - `POST /opro/generate_and_evaluate` - 生成初始候选
  - `POST /opro/refine` - 基于用户选择进行迭代改进
  - `GET /opro/sessions` - 获取所有会话
  - `GET /opro/runs` - 获取所有任务
- **会话管理**：支持多会话、多任务的并行管理
- **向后兼容**：保留原有查询重写功能，标记为 `opro-legacy`

### 5. 前端界面

- **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
```

### 访问界面

- **系统指令生成器**：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. **创建新会话**：在界面点击"新建会话"或侧边栏的 + 按钮
2. **输入任务描述**：例如"帮我写一个专业的营销文案生成助手"
3. **查看候选指令**：系统生成 5 个全面的系统指令，每个都以角色定义开头
4. **选择并改进**：点击喜欢的指令上的"继续优化"按钮，生成基于该指令的改进版本
5. **复制使用**：点击"复制"按钮将指令复制到剪贴板，用于你的应用中

## 配置说明

配置文件：`config.py`

### 关键配置项

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

# 生成参数
GENERATION_POOL_SIZE = 10  # 生成候选池大小（生成10个，聚类选择5个）
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 端点

### 会话管理

- `POST /opro/session/create` - 创建新会话
- `GET /opro/sessions` - 获取所有会话
- `GET /opro/session/{session_id}` - 获取会话详情

### 任务管理

- `POST /opro/create` - 在会话中创建新任务
  - 请求体：`{"session_id": "xxx", "task_description": "任务描述", "model_name": "qwen3:8b"}`
  - 返回：`{"run_id": "xxx", "task_description": "...", "iteration": 0}`

### 指令生成

- `POST /opro/generate_and_evaluate` - 生成初始候选指令
  - 请求体：`{"run_id": "xxx", "top_k": 5, "pool_size": 10}`
  - 返回：`{"candidates": [{"instruction": "...", "score": null}, ...]}`

- `POST /opro/refine` - 基于用户选择进行迭代改进
  - 请求体：`{"run_id": "xxx", "selected_instruction": "用户选择的指令", "rejected_instructions": ["被拒绝的指令1", "被拒绝的指令2"]}`
  - 返回：`{"candidates": [{"instruction": "...", "score": null}, ...], "iteration": 1}`

### 任务查询

- `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. 用户输入任务描述（如"帮我写一个专业的营销文案生成助手"）
2. 系统使用 LLM 生成 10 个候选指令
3. 通过语义嵌入和聚类算法选择 5 个最具多样性的候选
4. 所有候选都以角色定义开头，全面覆盖任务要求

### 迭代改进流程

1. 用户选择喜欢的指令（如候选 #3）
2. 系统记录被拒绝的指令（候选 #1, #2, #4, #5）
3. 向 LLM 发送改进请求："基于选中的指令生成改进版本，避免被拒绝指令的方向"
4. 生成新的 10 个候选，聚类选择 5 个返回
5. 用户可以继续迭代或复制使用

### 与 OPRO 的区别

**OPRO（原始算法）**：
- 需要测试用例（如数学题的正确答案）
- 自动评分（如准确率 0.73, 0.81）
- 基于性能轨迹优化
- 适用于有明确评估标准的任务

**本工具（简单迭代改进）**：
- 不需要测试用例
- 不需要自动评分
- 基于用户偏好改进
- 适用于任意通用任务

## 常见问题

### 1. 无法连接 Ollama 服务

确保 Ollama 服务正在运行：
```bash
ollama serve
```

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

### 2. 模型不可用

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

### 3. 生成速度慢

- 调整 `GENERATION_POOL_SIZE` 减少候选数量（如改为 6，返回 3 个）
- 使用更小的模型（如 `qwen3:4b`）
- 确保 Ollama 使用 GPU 加速

### 4. 生成的指令质量不高

- 提供更详细的任务描述
- 多次迭代改进，选择最好的继续优化
- 尝试不同的模型

### 5. 界面显示异常

硬刷新浏览器缓存：
- **Mac**: `Cmd + Shift + R`
- **Windows/Linux**: `Ctrl + Shift + R`

---

<details>
<summary><b>原始 README（点击展开）</b></summary>

- 项目简介

- 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

</details>