2025-12-05 15:47:44 +08:00
|
|
|
|
- 项目简介
|
|
|
|
|
|
|
|
|
|
|
|
- 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
|
