VersionGuard RAG

VersionGuard RAG 是一个面向技术支持场景的版本安全 RAG 项目。项目提供本地 Streamlit 演示、查询评测、扩展数据构建和外部版本化文档导入工具。

环境要求

• Windows PowerShell
• Python 3.10 或更高版本
• DeepSeek API Key
• 首次下载 embedding 模型时需要联网

1. 克隆项目

git clone https://github.com/fcsguyxcw/VersionGuard-RAG.git
cd VersionGuard-RAG

2. 创建环境并安装依赖

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e .

3. 准备本地 embedding 模型

这一步只需在首次运行时执行：

$env:PYTHONPATH = "src"
.\.venv\Scripts\python.exe -B scripts\prepare_embedding_model.py

模型会保存到项目的 model-assets 目录，后续运行会直接读取本地文件。

4. 启动 Streamlit 演示

运行下面的命令后，按提示输入真实的 DeepSeek API Key。不要把示例说明文字当作 Key：

$env:PYTHONPATH = "src"
$env:DEEPSEEK_API_KEY = Read-Host "请输入真实的 DeepSeek API Key"
$env:HF_HUB_OFFLINE = "1"
$env:TRANSFORMERS_OFFLINE = "1"
.\.venv\Scripts\python.exe -B -m streamlit run src\versionguard_rag\cloudtask_v2_query_demo_app.py --server.address 127.0.0.1 --server.port 9008

启动后访问：

http://localhost:9008

如果 9008 已被占用，将命令中的 --server.port 9008 和访问地址改成另一个可用端口。

按 Ctrl+C 停止服务。

运行测试

$env:PYTHONPATH = "src"
.\.venv\Scripts\python.exe -B -m unittest discover -s tests

运行查询评测

评测会调用 DeepSeek API。请先设置真实 Key，并确认本地 embedding 模型已经准备完成。

运行默认数据集：

$env:PYTHONPATH = "src"
$env:DEEPSEEK_API_KEY = Read-Host "请输入真实的 DeepSeek API Key"
$env:HF_HUB_OFFLINE = "1"
$env:TRANSFORMERS_OFFLINE = "1"
.\.venv\Scripts\python.exe -B -m versionguard_rag.cloudtask_v2_query_benchmark

运行扩展数据集：

.\.venv\Scripts\python.exe -B -m versionguard_rag.cloudtask_v2_query_benchmark --profile expanded

重新构建扩展数据

$env:PYTHONPATH = "src"
.\.venv\Scripts\python.exe -B scripts\build_cloudtask_v2_expanded.py

导入外部版本化文档

该命令会访问网络并重新生成外部文档快照与 lineage 文件：

$env:PYTHONPATH = "src"
.\.venv\Scripts\python.exe -B scripts\ingest_external_docs.py --sources data\external\airflow-task-docs\sources.json --output-dir data\external\airflow-task-docs