CPG2PVG-AI项目：临床指南转换工具部署与使用完整指南

本文记录了一个基于AI的临床指南转换项目（CPG2PVG-AI）的完整部署流程，包括环境配置、依赖安装、服务启动及常见问题解决方案。

项目概述

CPG2PVG-AI是一个基于FastAPI和Streamlit构建的智能工具，能够将专业的临床实践指南（CPG）转换为易于公众理解的版本（PVG）。项目采用模块化设计，支持多种大语言模型，具备PDF文档解析和流式输出等核心功能。

环境配置与依赖安装

首次安装步骤（只需执行一次）

1. 创建虚拟环境

# 进入项目目录
cd D:\Users\KRATZDISTELN\Desktop\STEFANO\TIDE\cursor_tide_fast

# 创建虚拟环境
python -m venv .venv

2. 配置国内镜像源（可选，加速下载）

.\.venv\Scripts\pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

3. 分批安装依赖包

# 基础后端依赖
.\.venv\Scripts\pip install fastapi==0.115.6 uvicorn==0.32.1 pydantic==2.11.7 typing-extensions==4.12.2 httpx==0.28.1 tenacity==9.0.0

# 前端依赖
.\.venv\Scripts\pip install streamlit==1.40.1 streamlit-extras==0.4.7

# 工作流与AI处理
.\.venv\Scripts\pip install langchain==0.3.26 langchain-openai==0.3.5 langgraph==0.2.56 langchain-text-splitters==0.3.8 jsonpatch==1.33

# 实用工具
.\.venv\Scripts\pip install python-dotenv==1.0.1 pypdf==5.1.0

重要提示：依赖安装完成后会保存在 .venv\Lib\site-packages 目录中，只要 .venv 目录存在，就无需重复安装。

日常使用流程

1. 配置API密钥

# 推荐使用 SiliconFlow（稳定可用）
$env:SILICONFLOW_API_KEY="你的_siliconflow_api_key"

# 其他可选模型（按需配置）
# $env:QWEN_API_KEY="你的_qwen_key"          # 阿里云通义千问
# $env:GAOCHAO_API_KEY="你的_gaochao_key"    # 高潮代理
# $env:DEEPSEEK_API_KEY="你的_deepseek_key"  # DeepSeek（注意网络连通性）

2. 启动后端服务（FastAPI）

# 检查并释放被占用的8012端口
$tcp = Get-NetTCPConnection -LocalPort 8012 -State Listen -ErrorAction SilentlyContinue | Select-Object -First 1
if ($tcp) { Stop-Process -Id $tcp.OwningProcess -Force }

# 启动后端服务
.\.venv\Scripts\python.exe .\CPG2PVG-AI\main.py

启动成功后访问：http://localhost:8012/docs 验证服务状态。

3. 启动前端界面（Streamlit）

在新PowerShell窗口中执行：

.\.venv\Scripts\streamlit.exe run .\CPG2PVG-AI\app.py --server.headless=true --server.port=8501

访问地址：http://localhost:8501

核心功能特性

文件格式支持

• Markdown文件：直接处理
• PDF文档：自动解析并转换为Markdown格式
  • 生成规则：原文件名_extracted.md
  • 依赖：pypdf库进行文本提取

模型配置选项

前端侧边栏支持多种LLM模型：

• qwen-sf (SiliconFlow) - 推荐
• deepseek - 需解决DNS解析问题
• gpt-4o-mini、gpt-5-mini - 通过高潮代理
• claude-small、qwen-long - 其他可选模型

输出配置

• Stream Output：支持流式/非流式输出
• 处理模式：
  • Public Version Fast（快速模式）
  • Public Version Slow（详细模式）
• 下载文件命名：PVG_原文件名.md

技术架构与关键改进

后端服务优化

• 端口管理：自动检测并处理8012端口占用问题
• 环境变量优先：API密钥从环境变量读取，增强安全性
• LangSmith控制：关闭外部追踪，避免网络依赖

前端功能增强

# 文件上传目录安全处理
upload_dir = os.path.join(os.path.dirname(__file__), "upload_files")
os.makedirs(upload_dir, exist_ok=True)

# PDF文本提取功能
def extract_pdf_text(pdf_path):
    # 使用pypdf解析PDF内容
    # 返回提取的文本并保存为Markdown格式

提示词系统升级

主要变更（2025-11-03版本）：

• 检查列表扩展：从8个通用问题扩展到20个细分问题

  • 预防（一级/二级预防）
  • 诊断（标准、流程、鉴别）
  • 治疗（药物、手术、介入等5类）
  • 预后与管理（监测、并发症、复发预防）
  • 特殊人群（儿童、老年、孕妇等4类）
  • 决策与沟通（风险评估、医患沟通等）

• 输出结构化：固定6个序列的输出格式

• 语言风格优化：强化患者视角，增加Mermaid图表指导

快速启动命令

将以下命令保存为批处理文件，实现一键启动：

backend.bat（后端启动）：

@echo off
cd /d D:\Users\KRATZDISTELN\Desktop\STEFANO\TIDE\cursor_tide_fast
set SILICONFLOW_API_KEY=你的_siliconflow_api_key
.\.venv\Scripts\python.exe .\CPG2PVG-AI\main.py
pause

frontend.bat（前端启动）：

@echo off
cd /d D:\Users\KRATZDISTELN\Desktop\STEFANO\TIDE\cursor_tide_fast
.\.venv\Scripts\streamlit.exe run .\CPG2PVG-AI\app.py --server.headless=true --server.port=8501
pause

常见问题解决方案

1. 端口占用错误（WinError 10048）

# 在启动后端前执行端口清理
Get-NetTCPConnection -LocalPort 8012 -State Listen | ForEach-Object { 
    Stop-Process -Id $_.OwningProcess -Force 
}

2. 模型返回空内容

• 原因：API密钥无效、额度不足或网络连接问题
• 解决方案：
  1. 确认环境变量设置正确
  2. 推荐使用SiliconFlow（qwen-sf）模型
  3. 检查网络连通性

3. PDF上传失败

• 检查项目：
  1. 确认upload_files目录自动创建
  2. 验证pypdf依赖正常安装
  3. 重新上传文件尝试

4. 依赖安装缓慢

• 已配置清华镜像源
• 可尝试分批次安装或切换网络环境

5. 虚拟环境激活问题

无需激活，直接使用绝对路径执行：

.\.venv\Scripts\python.exe    # 代替 python
.\.venv\Scripts\streamlit.exe # 代替 streamlit

项目结构说明

cursor_tide_fast/
├── CPG2PVG-AI/
│   ├── main.py              # FastAPI后端主程序
│   ├── app.py               # Streamlit前端界面
│   ├── llms.py              # 模型配置与管理
│   ├── chains/
│   │   └── all_prompts.py   # 提示词系统（已升级）
│   └── upload_files/        # 文件上传目录（自动创建）
├── .venv/                   # 虚拟环境目录
└── 运行指南文档

总结

CPG2PVG-AI项目通过系统的环境配置和模块化设计，提供了一个稳定可靠的临床指南转换解决方案。关键成功要素包括：

1. 环境隔离：使用虚拟环境确保依赖一致性
2. 多模型支持：灵活的LLM接入方案
3. 文件兼容：完善的PDF解析能力
4. 错误处理：全面的异常情况处理机制
5. 用户体验：直观的前端界面和操作流程

按照本文指南，用户可以顺利完成从环境搭建到日常使用的全过程，有效将专业医疗文档转换为公众易读版本。

---

注意事项：

• 首次安装只需执行一次，日常使用仅需启动服务
• 推荐使用SiliconFlow模型保证稳定性
• 定期检查API密钥额度和项目更新