Stonewalker20/TrustStack

# TrustStack TrustStack 将 AI 评估转化为一次引导式任务。用户可以上传源材料，运行接地查询，检查证据，审查置信度和风险信号，并在以太阳系为灵感的界面中完成整个工作流。 ## TrustStack 的功能 TrustStack 旨在回答一个实际问题： **用户不仅能理解模型说了什么，还能理解为什么应该或不应该信任它？** 它结合了以下能力： - 文档摄取与索引 - 检索增强回答 - 置信度评分 - 风险标记生成 - 证据检查 - 运行历史追踪 - 一个可视化前端，引导用户完成每个评估阶段 ## 课程项目契合度 TrustStack 是一个全面的模型评估与接地 AI 分析项目，适用于 CSI-4130/5130。它从三个方面契合课程要求： - `全面的模型评估` TrustStack 使用以证据为先的标准化评分框架、一致性检查、矛盾分析以及可基准化的报告工件来评估生成式 AI 输出。 - `使用现代 AI 的应用开发` 该系统是一个完整的前后端应用，包含浏览器前端、FastAPI 后端、MongoDB 持久化、检索、本地模型集成以及可复现的导出/报告路径。 - `真实世界问题聚焦` 项目针对一个实际部署问题：用户常常收到流畅的 AI 输出，却缺乏可靠的方法来判断这些输出是否足够接地、可信。 ## 问题陈述 现代 LLM 系统易于演示但难以信任。在政策、研究、安全和合规场景中，用户需要的不仅仅是一个答案：他们需要证据可追溯性、矛盾检查、置信度校准，以及关于响应是否安全可操作化的明确指导。 TrustStack 通过将信任视为一种首要的评估输出而非模糊的主观印象来解决这一问题。 ## 提议的方法 TrustStack 采用本地优先的检索与评估工作流： 1. 摄取用户证据并将其分块为已索引的片段 2. 检索与问题最相关的片段 3. 生成带引用的接地答案 4. 使用 TrustStack 评估标准 v2.0 对答案评分 5. 返回证据诊断、风险标记、解释说明和可导出的报告工件 这使得系统既是一个应用，也是一个评估框架。 ## 数据来源 TrustStack 目前使用两类数据： - 用户上传的证据文件（`.pdf`、`.docx`、`.txt` 和 `.md`） - 用于评估的控制基准语料库 当前支持的基准包括： - 用于可重复压力测试的合成证据包 - `FEVER` 用于主张验证 - `SciFact` 用于科学主张验证 - `HotpotQA` 用于多跳接地问题回答 后端支持 `backend/data/benchmarks/` 中的标准化本地基准文件，并为支持的公共数据集提供可选的 Hugging Face 数据集加载。 ## 功能地图 ### 前端体验 - 以太阳系为引导的着陆页与基于行星的工作流 - 专注的页面：摄取、实时查询、证据审查、风险摘要、历史记录、蓝图与方法论 - 任务控制模式，供希望在一个屏幕上完成完整工作流的用户使用 ### 后端能力 - 对 `.pdf`、`.docx`、`.txt` 和 `.md` 的文件上传与解析 - 源材料的分块与索引 - 对存储片段的检索 - 接地答案生成 - 信任评分与风险标签 - 详细的解释负载，帮助用户理解评分是如何形成的 ### 可靠性层 - 基于检索质量、引用覆盖率和答案行为的置信度评分 - 弱支持、缺失引用、证据不足及操作风险语言的标记 - 解释负载，展示： - 评分分解 - 证据强度 - 引用覆盖率 - 标记的关注点 - 审查建议 ## 技术栈 | 层 | 技术 | | --- | --- | | 前端 | React, Vite, TypeScript | | 后端 API | FastAPI | | 文档存储 | MongoDB | | 向量检索 | ChromaDB 或简单的本地向量存储后备 | | 嵌入 | Ollama 嵌入、本地 sentence-transformers 或词法后备 | | 大语言模型 | Ollama、开源兼容 API 或提取式后备 | | 测试 | Python `unittest` | ## 快速启动 ### 1. 拉取本地模型 ``` ollama pull qwen2.5:7b-instruct ollama pull nomic-embed-text ``` 如果你的机器内存紧张： ``` ollama pull qwen2.5:3b-instruct ``` ### 2. 启动 MongoDB TrustStack 现在需要 MongoDB 来存储文档、片段和运行历史。 默认连接： ``` mongodb://127.0.0.1:27018 ``` 默认数据库： ``` truststack ``` 推荐的本地运行时（使用 Docker）： ``` docker compose up -d mongo docker compose ps ``` 停止运行： ``` docker compose stop mongo ``` ### 3. 启动后端 ``` cd backend python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt cp .env.example .env uvicorn app.main:app --reload ``` 如果使用包含的 Docker MongoDB 设置，默认 `.env` 值已指向它： ``` MONGO_URI=mongodb://127.0.0.1:27018 MONGO_DB_NAME=truststack ``` 可选的检索升级： ``` pip install -r requirements-optional.txt ``` ### 4. 启动前端 ``` cd frontend npm install npm run dev ``` 前端默认： ``` http://127.0.0.1:5173 ``` 后端默认： ``` http://127.0.0.1:8000 ``` ## API 接口 | 端点 | 用途 | | --- | --- | | `GET /health` | 检查后端可用性 | | `POST /ingest` | 上传并索引文档 | | `POST /query` | 运行接地查询并返回答案、证据、评分、风险与解释 | | `GET /runs` | 检索最近的评估历史 | | `GET /documents` | 检索已索引的文档列表 | | `POST /evaluation/standard-run` | 在当前索引语料库上运行 TrustStack 标准化套件 | | `POST /evaluation/standard-run/batch` | 独立比较每个索引源文件上的 TrustStack | | `POST /evaluation/real-benchmark` | 在真实基准数据集（如 FEVER、SciFact 和 HotpotQA）上运行 TrustStack | ## 运行测试 后端测试： ``` cd backend ./.venv/bin/python -m unittest discover -s tests -v ``` 真实 MongoDB 集成测试： ``` docker compose up -d mongo cd backend ./.venv/bin/python -m unittest tests.test_integration_mongo -v ``` 项目级验证： ``` npm run verify:frontend npm run verify:backend:unit npm run verify:backend:integration npm run verify:e2e npm run verify:smoke ``` 后端套件当前覆盖： - 健康端点行为 - 摄取验证 - 查询成功与失败路径 - 运行历史检索 真实基准数据集： - 安装 `backend/requirements-optional.txt` 以启用 Hugging Face 数据集加载 - 或将标准化 JSONL 基准文件放入 `backend/data/benchmarks/` - 当前支持的基准键包括 `fever`、`scifact` 和 `hotpotqa` - 真实 MongoDB 支持的摄取、查询、文档与运行历史集成 - 命中提取 - 置信度评分 - 风险标记 - 解释生成 - 由仓库驱动的索引重建行为 浏览器端到端覆盖现在包括： - 针对实时本地后端的真实前端 - 从 UI 真实上传文档 - UI 中的示例问题生成 - 通过浏览器执行接地查询 - 实时评估后的下游风险与运行历史视图 生产环境类烟雾测试现在包括： - 通过 `vite preview` 提供的前端静态资源 - 通过 `uvicorn` 提供的实时 FastAPI 后端 - 实时运行的 MongoDB 容器 - 针对已部署堆栈的端到端浏览器验证 ## 评估摘要 TrustStack 当前评估： - 检索相关性 - 证据充分性 - 引用可追溯性 - 主张支持 - 矛盾风险 - 完整性 - 诚实性与弃权 - 答案规范性 - 安全与操作风险 - 校准与一致性 该仓库还包括： - 后端单元测试 - 真实 MongoDB 集成测试 - 浏览器端到端测试 - 已部署堆栈的烟雾测试 - 用于 IEEE 报告的合成基准生成 - 真实基准数据集支持（FEVER、SciFact、HotpotQA） ## 演示资产 课堂演示支持： - `frontend/` 中的交互式前端 - `docs/report/main.pdf` 中的最终报告 PDF - 嵌入前端体验中的星球视角演示流程 在最终课程提交前，请将录制演示视频的公开链接添加到此 README。 ## 环境说明 `backend/.env` 中的重要后端设置： ``` MONGO_URI=mongodb://127.0.0.1:27018 MONGO_DB_NAME=truststack CHROMA_PERSIST_DIR=./data/chroma UPLOAD_DIR=./data/uploads EMBEDDING_PROVIDER=ollama EMBEDDING_MODEL=nomic-embed-text LLM_PROVIDER=ollama LLM_MODEL=qwen2.5:7b-instruct ``` 后端针对受限本地环境的回退机制： - 如果外部嵌入不可用，则使用词法嵌入回退 - 如果模型生成不可用，则使用提取式答案回退 - 当检索索引为空时，从持久化片段重建向量索引 ## 安全说明 当前保护措施包括： - 文件名净化 - 唯一的存储上传名称 - 上传大小限制 - 扩展名允许列表 - 提供商不可用时的更安全回退执行路径 在公开部署前，请添加： - 身份验证 - 速率限制 - 更严格的 CORS - 上传恶意软件扫描 - 更安全的文件解析隔离 - 密钥管理 ## 项目结构 ``` TrustStack/ ├── backend/ │ ├── app/ │ ├── data/ │ ├── tests/ │ └── requirements.txt ├── frontend/ │ ├── public/ │ └── src/ ├── docs/ ├── sample_data/ └── README.md ``` ## 当前方向 TrustStack 正朝着一个更完善的本地优先 AI 评估平台发展，具备： - 更强 MongoDB 后端的文档层 - 更丰富的解释与教学输出 - 健壮的离线回退行为 - 更适合生产的前导式前端 如果你接下来要参与该项目，优先级最高的领域是： 1. 实时 MongoDB 运行验证 2. 针对真实数据库的后端集成测试 3. 更丰富的前端解释负载渲染 4. 更紧密的摄取与检索可观测性 ## 引用与致谢 TrustStack 基于已发布的工作和开源工具构建。关键研究参考文献记录在 [references.bib](docs/report/references.bib) 中，并在最终报告中引用。主要的软件与数据集依赖包括： - FastAPI - React 和 Vite - MongoDB - ChromaDB - Ollama - Hugging Face 数据集 - FEVER - SciFact - HotpotQA 最终报告的源文件在 [main.tex](docs/report/main.tex) 中，编译后的 PDF 位于 [main.pdf](docs/report/main.pdf)。报告中的所有基准表格均从项目工件生成，而非手动转录。

标签：AI风险缓解, AV绕过, CSI-4130, CSI-5130, FastAPI, grounded AI, HTML报告, LLM可靠性, MongoDB, RAG, schema可靠性, 事实性评估, 全栈应用, 公开仪表盘, 前端可视化, 反取证, 可追溯性, 合规评估, 大语言模型评估, 太阳系界面, 安全评估, 工具可靠性, 开源评估框架, 护栏有效性, 指标JSON, 排行榜, 政策评估, 文档摄取, 检索增强生成, 模型评估, 生成式AI, 真实世界问题, 矛盾分析, 稳定性评估, 索引, 置信度校准, 置信度评分, 证据检查, 课程项目, 输出可信赖性, 运行历史追踪, 逆向工具, 风险标记