JieChiang/VRS-Zhiyuan-Recommendation

选用指南

AI 根据 README 整理 · 2026/10/20 02:51:20

适用场景

适用于浙江考生或规划人员，基于历史录取数据生成冲稳保候选，并支持院校对比、专业介绍、成绩轨迹分析等。

查看 README 依据

# VRS 志愿推荐系统 基于 **FastAPI、Neo4j 知识图谱与 DeepSeek** 的高考志愿规划示例系统。当前业务范围是**浙江生源、2019–2024 年历史录取参考**。用户输入位次、选科、专业领域和意向省市，生成冲稳保候选，并查看来源、历年趋势及 AI 辅助分析。 公开仓库包含代码、环境配置样例、**14 份 Excel 合成示例模板**，以及从本地已构建 Neo4j 导出的**完整浙江历史知识图谱快照**。克隆后可直接导入，无需先收集原始 Excel。快照包含公开招生事实及其来源，不包含考生成绩、SQLite、数据库账户、密码或 API Key；真实原始 Excel 不随仓库分发。 ## 功能 | 模块 | 功能 | | --- | --- | | 规划工作台 | 分数与浙江位次、三门选科、专业领域、意向省市、目标院校、策略参数、草稿保存 | | 志愿推荐 | 全量历史候选、可选位次窗口、选科子集匹配、冲稳保分层、搜索筛选、来源行号、待核实记录 | | 院校对比 | 同校同招生专业的历年最低分、位次、计划、排名及满意度 | | 专业介绍 | 三级目录、原始简介、学位信息、AI 解读、职业路径与市场探索 | | 成绩轨迹 | 文本录入、图片 OCR、成绩整理、趋势图与优势分析 | | 模拟沙箱 | 改变位次和偏好，比较两份候选方案 |

使用方式

通过命令行启动Web服务，访问http://127.0.0.1:8000使用；也可通过Windows批处理或可选桌面入口启动。

查看 README 依据

.\.venv\Scripts\python.exe run_server.py ``` 打开 [应用首页](http://127.0.0.1:8000) 或 [接口文档](http://127.0.0.1:8000/docs)。演示登录接受非空用户名与密码，请使用临时演示内容。当前登录和部分 API 不具备正式多用户鉴权，公开的是代码仓库，不代表应用已经适合直接部署到公网。 如需保持开发预览端口8765： ```powershell .\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8765 ``` ### Windows 双击启动（已有 Conda 环境） 双击根目录的 `启动项目.bat`。脚本默认激活 `D:\Software\Miniconda3\envs\VRS`，使用该环境的 Python 检查依赖，缺少依赖时按 `requirements.txt` 安装，再启动项目并在页面就绪后自动打开 `http://127.0.0.1:8765`。这套启动方式另在 Python 3.11.15 的 Conda 环境验证通过。

其他机器需要把 BAT 中的 `VRS_CONDA_ENV` 和 Miniconda `activate.bat` 路径改为自己的安装位置。请先启动 Neo4j，配置自己的数据库密码与 API Key；BAT 不包含凭据、不修改私有配置，也不会自动启动 Neo4j。重复双击会复用已运行的 VRS 服务；端口被其他程序占用时会提示错误。关闭首次启动的控制台窗口或按 Ctrl+C 可停止 Web 服务。 ```powershell # 可选：仅启动服务，不自动打开浏览器 .\启动项目.bat --no-browser ``` 可选桌面入口：安装统一的 `requirements.txt` 后运行 `desktop_app.py`，无需额外安装其他 requirements 文件。该入口保留，但尚未做 PyQt 窗口验收。`/api/v1/health` 为兼容健康接口，模型 `configured` 仅代表配置存在；登录后的 `/api/v1/setup/status` 提供独立的环境检查，`POST /api/v1/setup/verify-model` 手动验证模型访问。 ## 推荐规则与数据范围 - 默认 `candidate_scope=all` 检索符合条件的全部历史位次，再排序分层。只有显式 `window` 才使用位次窗口，避免把较安全的候选截掉。

部署要求

需要Python 3.12、Neo4j Community、Java/JDK，以及DeepSeek API密钥用于AI功能；默认使用云端模型，不要求本地GPU或Ollama。

查看 README 依据

| 测试 | unittest、FastAPI TestClient/httpx、Node.js 前端逻辑检查 | 无需 npm 安装或前端构建，页面资源由 FastAPI 直接提供。所有 Python 依赖统一放在 `requirements.txt`，包含 Web 运行、接口测试和 PyQt 桌面入口所需依赖。 ## 环境与外围软件 已在 Windows、Python 3.12.14、Neo4j Community 2026.04.0 和 Java 25 上验证。其他 Neo4j 版本请先确认其 Java 要求及 HTTP 事务接口兼容性。默认使用云端模型，不要求本地 GPU 或 Ollama。 | 软件 | 是否必需 | 安装或使用链接 | | --- | --- | --- | | Python 3.12（64位） | 必需 | [Python 下载](https://www.python.org/downloads/windows/) | | Git | 克隆和提交时需要 | [Git 下载](https://git-scm.com/downloads) |

| Neo4j Community | 图谱与推荐必需 | [下载](https://neo4j.com/deployment-center/) · [Windows 安装](https://neo4j.com/docs/operations-manual/current/installation/windows/) | | Java/JDK | 运行独立 Neo4j 必需 | [Neo4j 系统要求](https://neo4j.com/docs/operations-manual/current/installation/requirements/) · [Temurin JDK 下载](https://adoptium.net/temurin/releases/) | | DeepSeek API | 六项 AI 功能需要 | [平台与密钥](https://platform.deepseek.com/) · [API 文档](https://api-docs.deepseek.com/) |

已知限制

当前业务范围仅限浙江生源2019-2024年历史录取参考；登录和部分API不具备正式多用户鉴权，不适合直接部署到公网；概率与策略权重尚未用真实录取样本校准。

查看 README 依据

# VRS 志愿推荐系统 基于 **FastAPI、Neo4j 知识图谱与 DeepSeek** 的高考志愿规划示例系统。当前业务范围是**浙江生源、2019–2024 年历史录取参考**。用户输入位次、选科、专业领域和意向省市，生成冲稳保候选，并查看来源、历年趋势及 AI 辅助分析。 公开仓库包含代码、环境配置样例、**14 份 Excel 合成示例模板**，以及从本地已构建 Neo4j 导出的**完整浙江历史知识图谱快照**。克隆后可直接导入，无需先收集原始 Excel。快照包含公开招生事实及其来源，不包含考生成绩、SQLite、数据库账户、密码或 API Key；真实原始 Excel 不随仓库分发。 ## 功能 | 模块 | 功能 | | --- | --- | | 规划工作台 | 分数与浙江位次、三门选科、专业领域、意向省市、目标院校、策略参数、草稿保存 | | 志愿推荐 | 全量历史候选、可选位次窗口、选科子集匹配、冲稳保分层、搜索筛选、来源行号、待核实记录 | | 院校对比 | 同校同招生专业的历年最低分、位次、计划、排名及满意度 | | 专业介绍 | 三级目录、原始简介、学位信息、AI 解读、职业路径与市场探索 | | 成绩轨迹 | 文本录入、图片 OCR、成绩整理、趋势图与优势分析 | | 模拟沙箱 | 改变位次和偏好，比较两份候选方案 |

.\.venv\Scripts\python.exe run_server.py ``` 打开 [应用首页](http://127.0.0.1:8000) 或 [接口文档](http://127.0.0.1:8000/docs)。演示登录接受非空用户名与密码，请使用临时演示内容。当前登录和部分 API 不具备正式多用户鉴权，公开的是代码仓库，不代表应用已经适合直接部署到公网。 如需保持开发预览端口8765： ```powershell .\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8765 ``` ### Windows 双击启动（已有 Conda 环境） 双击根目录的 `启动项目.bat`。脚本默认激活 `D:\Software\Miniconda3\envs\VRS`，使用该环境的 Python 检查依赖，缺少依赖时按 `requirements.txt` 安装，再启动项目并在页面就绪后自动打开 `http://127.0.0.1:8765`。这套启动方式另在 Python 3.11.15 的 Conda 环境验证通过。

- 选科按“学校要求是考生选科的子集”核验；不限或有匹配计划的空白要求对任意组合开放；没有匹配计划则待核实。 - 完整填写三门时，主推荐仅包含已满足明确选科要求的历史项目，未知要求单列；只填一两门时保留未知探索候选。 - 专业类优先于同名门类，支持“法学专业”“法学门类”、财会与师范等解释，页面显示实际范围。 - 默认80条、最多300条；比例为0的冲/稳/保层不参与推荐或补足。沿用±300位次分界，概率与策略权重尚未用真实录取样本校准。 - 分数不作第二次硬过滤。当前缺少一分一段表、批次和完整招生限制，选科符合不等于完成所有报考资格认证。 - 原计划表选科是行级要求，没有逐年分别列示。增加年份、生源省份或政策结构时，需要同步代码、数据范围和测试。 六项 AI 功能统一调用云端：问答、专业介绍、成绩整理、优势分析、职业模拟、市场探索。服务端重新检索图谱证据，模型输出不作为录取事实；问答不会把少量上下文节选说成全部候选。市场评分为模型意见，没有实时就业统计保证。调用会发送问题、相关成绩文本和少量证据到 DeepSeek，并消耗对应 API 额度。 ## 测试 ```powershell .\.venv\Scripts\python.exe -m pip install -r requirements.txt