{"repo": "benjamindaoson/aiedurag", "files": {"README.zh-CN.md": {"bb913bf73d980e644b868f31d26ff8940d086ee5": {"t": 1786068586.189571, "n": 8089, "h": "317c71dd574ae496", "c": "<div align=\"center\">\n\n# StuckToShip\n\n### 从卡住到做出来的 AI 工程课程助教。\n\n<p>\n  <a href=\"README.md\">English</a> | <strong>简体中文</strong>\n</p>\n\nStuckToShip 面向正在学习大模型应用、RAG、LangGraph、Milvus、MCP 和 Agent 的人。\n\n它把课程讲义、项目代码、FAQ、报错经验和评估记录连起来，帮助学生知道自己卡在哪里、为什么卡、下一步怎么做。\n\n[快速开始](#快速开始) | [为什么值得用](#为什么值得用) | [功能](#功能) | [数据](#放入你的课程数据) | [评估](#评估) | [路线图](#路线图)\n\n![Python](https://img.shields.io/badge/Python-3.12+-3776AB?style=flat&logo=python&logoColor=white)\n![FastAPI](https://img.shields.io/badge/FastAPI-0.136-009688?style=flat&logo=fastapi&logoColor=white)\n![LangGraph](https://img.shields.io/badge/LangGraph-workflow-1C3C3C?style=flat)\n![Milvus](https://img.shields.io/badge/Milvus-vector%20search-00A1EA?style=flat)\n![Tests](https://img.shields.io/badge/tests-111%20passed-brightgreen?style=flat)\n\n</div>\n\n---\n\n## 为什么值得用\n\n学 AI 工程最痛的不是没人解释概念，而是卡点总是混在一起：\n\n- 课上讲了 RAG，但项目里到底在哪里实现？\n- 文档看了，但代码还是跑不起来。\n- 报错日志里一堆依赖、配置、API Key、向量库问题，哪个才是根因？\n- 问普通 ChatGPT，回答很顺，但和当前课程、当前代码对不上。\n- 知道要学 LangGraph、MCP、reranking、evaluation，却不知道先学哪个。\n- 改了切片、检索或 prompt，效果到底变好了还是变差了？\n\nStuckToShip 的核心判断很简单：\n\n> 好的 AI 课程助教，不应该只回答问题。它应该把学生从“我卡住了”带到“我懂了，也能做出来”。\n\n所以它会先判断问题类型，再去找课程、代码、报错或 FAQ 证据，用听得懂的方式解释，并给出下一步。可信、有出处是底线；真正的价值是帮学习者打通卡点。\n\n## 你可以问什么\n\n```text\nRAG 在大模型应用里到底解决什么问题？\n请给我一个 Agent RAG 的学习路径。\ncreate_app 在 main.py 里是怎么启动项目的？\n为什么 chunk size 会影响答案质量？\nModuleNotFoundError: No module named pymilvus\nDashScope API Key 怎么配置？\n```\n\n一次回答可以带回：\n\n```json\n{\n  \"route\": \"course\",\n  \"answer\": \"...\",\n  \"references\": [\n    {\n      \"source_file\": \"knowledge/courses/rag-basics.md\",\n      \"source_type\": \"course_note\",\n      \"score\": 6.0\n    }\n  ],\n  \"trace\": {\n    \"route_reason\": \"default_course_route\",\n    \"decision\": \"accept\",\n    \"latency_ms\": 12\n  }\n}\n```\n\n## 功能\n\n| 功能 | 当前状态 |\n|---|---|\n| 学习卡点路由 | 识别课程、学习路径、代码、报错和 FAQ 问题 |\n| 课程资料答疑 | 从 `knowledge/courses/` 读取 Markdown/TXT 课程资料 |\n| 学习路径推荐 | 把 roadmap 类问题路由到课程大纲证据 |\n| 代码库问答 | 用 Python AST 建立符号索引 |\n| 报错诊断 | 匹配结构化 setup/runtime error recipe |\n| FAQ 优先 | 高频问题先走 FAQ，减少无意义生成 |\n| 证据门控 | 证据不足时拒答或追问 |\n| 引用 | 返回来源文件、来源类型、分数和文本 |\n| Trace | 展示路由、候选证据、门控决策、引用和延迟 |\n| 流式输出 | 支持 `/api/v1/rag/ask-stream` |\n| Web 控制台 | 聊天、引用面板、route pill、trace preview、评估页 |\n| 离线评估 | 32 条 Agent 课程评估集，当前路由准确率 32/32 |\n| 完整向量检索 | 已提供 Docker Milvus 配置 |\n\n## 快速开始\n\n每个项目都必须使用独立 `.venv`，不要把依赖装进全局 Python。\n\n```powershell\ncd C:\\path\\to\\stucktoship\n\npy -3.12 -m venv .venv\n.\\.venv\\Scripts\\python.exe -m pip install -r requirements.txt\nCopy-Item .env.example .env\n\n.\\.venv\\Scripts\\python.exe -m uvicorn main:app --host 127.0.0.1 --port 8010\n```\n\n打开：\n\n```text\nhttp://127.0.0.1:8010\n```\n\n健康检查：\n\n```powershell\nInvoke-RestMethod http://127.0.0.1:8010/health\n```\n\n## API 示例\n\n```powershell\n$body = @{\n  query = \"RAG 在大模型应用里到底解决什么问题？\"\n  stream = $false\n} | ConvertTo-Json\n\nInvoke-RestMethod `\n  -Method Post `\n  -Uri http://127.0.0.1:8010/api/v1/rag/ask `\n  -ContentType application/json `\n  -Body $body\n```\n\n流式接口：\n\n```text\nPOST /api/v1/rag/ask-stream\n```\n\n评估历史：\n\n```text\nGET /api/v1/evaluation/history?limit=50\n```\n\n## 它怎么工作\n\n```mermaid\nflowchart LR\n  Q[\"学生问题\"] --> R[\"学习卡点路由\"]\n  R -->|course| C[\"课程资料\"]\n  R -->|learning_path| L[\"学习路径\"]\n  R -->|code| K[\"代码符号\"]\n  R -->|error| E[\"报错方案\"]\n  R -->|faq| F[\"FAQ\"]\n  C --> G[\"证据门控\"]\n  L --> G\n  K --> G\n  E --> G\n  F --> G\n  G --> A[\"基于证据解释\"]\n  A --> O[\"答案 + 引用 + Trace\"]\n```\n\n### 演进架构：统一教学 RAG 引擎\n\n下一阶段不会把 Hybrid RAG、GraphRAG、Agentic RAG 和 Multimodal RAG 做成四套独立系统，而是让一个受控的教学 Agent 根据问题选择合适的检索能力。现有的证据门控、纠错重试、拒答和自动化评测将成为所有检索路径共用的质量护栏。\n\n> 下面是目标架构。Hybrid 检索、纠错门控和评测已有实现基础；GraphRAG、Agent Planner 和多模态检索仍在路线图中。\n\n```mermaid\nflowchart TD\n    Q[\"学员问题 / 图片 / 代码 / 报错\"] --> U[\"统一意图分析与必要澄清\"]\n    U --> P[\"受预算约束的 Agent Planner\"]\n\n    P --> H[\"Hybrid Retriever\"]\n    P --> G[\"Concept + Code Graph Retriever\"]\n    P --> C[\"AST / Code Retriever\"]\n    P --> M[\"Multimodal Retriever\"]\n    P --> F[\"FAQ / Error Retriever\"]\n\n    H --> X[\"统一 EvidenceSet\"]\n    G --> X\n    C --> X\n    M --> X\n    F --> X\n\n    X --> R[\"融合去重 + Cross-Encoder Rerank\"]\n    R --> E[\"Corrective Evidence Grader\"]\n\n    E -->|证据充分| A[\"教学型答案生成\"]\n    E -->|覆盖不足| P\n    E -->|问题模糊| Q2[\"追问澄清\"]\n    E -->|没有可靠证据| N[\"明确拒答\"]\n\n    A --> O[\"答案 + 行号/页码/时间戳 + 下一步练习\"]\n    O --> V[\"自动化评测与反馈闭环\"]\n```\n\n| 检索能力 | 解决的问题 | 状态 |\n|---|---|---|\n| Hybrid RAG | 同时理解概念语义和 API、文件名、报错关键词 | 已有 dense、BM25、RRF 和 rerank 基础，待统一到课程助教主链路 |\n| GraphRAG | 回答先修关系、概念关系、代码调用链和配置依赖 | 规划中 |\n| Agentic RAG | 按问题动态选择课程、代码、图谱、报错和多模态工具 | 规划中 |\n| Multimodal RAG | 理解 PDF/PPT 中的图表、架构图、代码截图和课程视频 | 规划中 |\n| Corrective RAG | 证据不足时改写、换检索策略、追问或拒答 | 已有质量门控和有限重试基础 |\n\n关键文件：\n\n| 文件 | 作用 |\n|---|---|\n| `main.py` | FastAPI app factory 和运行时初始化 |\n| `services/rag_service.py` | RAG 服务入口、SSE、orchestrator 接入 |\n| `core/qa_orchestrator.py` | Agent 课程问答主流程 |\n| `core/intent_router.py` | 问题路由 |\n| `core/course_retriever.py` | 课程资料检索 |\n| `core/evidence.py` | 构建证据包 |\n| `core/retrieval_gate.py` | 证据门控 |\n| `ingestion/code_indexer.py` | Python 代码符号抽取 |\n| `evaluation/agent_course_eval.py` | 离线评估 |\n| `static/index.html` | 单文件 Web 控制台 |\n\n## 放入你的课程数据\n\nMVP 数据放这里：\n\n```text\nknowledge/\n  courses/    # 课程讲义、大纲、PPT 转文本、字幕\n  faq/        # 高频问题 JSONL\n  errors/     # 报错解决方案 JSONL\n```\n\n仓库自带种子数据：\n\n```text\n12 course documents\n15 FAQ rows\n10 error recipes\n40 evaluation questions\n60 public learner-question seeds\n```\n\n要让它真正好用，按这个顺序补数据：\n\n1. 学员真实问过的问题。\n2. 课程讲义、项目讲解、字幕、PPT 转 Markdown。\n3. 环境报错和验证过的修复命令。\n4. 项目 README、配置文件、入口文件、关键源码。\n5. 包含可回答、模糊、应该拒答问题的小评估集。\n\n验证后导入：\n\n```powershell\n.\\.venv\\Scripts\\python.exe scripts\\edu_rag.py import-course C:\\path\\to\\my-course-data --overwrite\n```\n\n源目录格式：\n\n```text\nmy-course-data/\n  courses/  # .md / .txt 课程资料\n  faq/      # JSONL，必须有 question + answer\n  errors/   # JSONL，必须有 error_pattern + symptom + cause + fix_steps\n  eval/     # JSONL，必须有 question + expected_route + should_answer\n```\n\n具体字段、最小数据量和清洗规则见 [`docs/course-data-requirements.md`](docs/course-data-requirements.md)。\n\n建议的最小私有数据量：\n\n```text\n10-30 篇课程资料\n50-100 条 FAQ\n20-50 条报错方案\n50-100 条评估问题\n1-3 个课程项目代码库\n```\n\n## 评估\n\n离线路由评估：\n\n```powershell\n.\\.venv\\Scripts\\python.exe -m evaluation.agent_course_eval --file data/agent_course_eval/manual_v1.jsonl --json\n```\n\n当前结果：\n\n```text\ntotal: 32\ncorrect: 32\nroute_accuracy: 1.0\n```\n\n完整回归测试：\n\n```powershell\n.\\.venv\\Scripts\\python.exe -m pytest -q\n```\n\n当前结果：\n\n```text\n111 passed, 8 warnings\n```\n\n## Milvus\n\nWindows 本地的课程、FAQ、报错和代码检索可以不依赖 Milvus 运行。\n\n如果你要上传文档并做完整向量检索，启动 Docker Milvus：\n\n```powershell\ndocker compose -f docker-compose.milvus.yml up -d\n$env:STUCKTOSHIP_MILVUS_URI = \"http://127.0.0.1:19530\"\n.\\.venv\\Scripts\\python.exe -m uvicorn main:app --host 127.0.0.1 --port 8010\n```\n\n停止：\n\n```powershell\ndocker compose -f docker-compose.milvus.yml down\n```\n\n## 配置\n\n常用 `.env`：\n\n```text\nLLM_API_KEY=ollama\nLLM_BASE_URL=http://localhost:11434/v1\nLLM_MODEL=glm-4.7-flash\n\nAPP_MODE=agent_course\nENABLE_TRACE=true\nENABLE_EVALUATION_API=true\nKNOWLEDGE_DIR=./knowledge\nCODE_RAG_ROOTS=.\nEVAL_DATASET=./data/agent_course_eval/manual_v1.jsonl\nSTUCKTOSHIP_MILVUS_URI=./stucktoship_milvus.db\nSTUCKTOSHIP_API_KEYS=\n```\n\n只要是 OpenAI-compatible 模型服务都可以接：DeepSeek、Ollama、DashScope、OpenAI-compatible gateway 或你自己的代理。如果系统环境变量里已有 `DEEPSEEK_API_KEY`，且没有设置 `LLM_API_KEY`，应用会直接使用 `DEEPSEEK_API_KEY`。\n\n## 路线图\n\n- [x] 课程、代码、FAQ、报错、学习路径路由\n- [x] API 和 UI 返回引用与 trace\n- [x] Agent 课程离线评估集\n- [x] 外部 Milvus Compose 配置\n- [x] 课程数据导入 CLI\n- [x] 检索文档 Prompt Injection 防护\n- [x] API Key 认证、基础文档 ACL、生产 Docker 模板\n- [ ] 统一课程助教与 LangGraph 链路，完整接入 Hybrid RAG 和 rerank 评估\n- [ ] 构建 AI 概念图与代码调用图，支持教学型 GraphRAG\n- [ ] 增加有调用预算、停止条件和可信工具白名单的 Agent Planner\n- [ ] 支持 PDF/PPT 图表、代码截图和视频时间戳的 Multimodal RAG\n- [ ] 数据集、chunk、prompt、model 版本追踪\n- [ ] 反馈到 FAQ / error recipe 的半自动闭环\n\n## 常见问题\n\n### 页面打不开？\n\n先看终端有没有：\n\n```text\nUvicorn running on http://127.0.0.1:8010\nGET / HTTP/1.1\" 200 OK\n```\n\n如果有 `200 OK`，说明服务已经返回页面。浏览器按 `Ctrl+F5` 强刷。\n\n### 评估接口 404？\n\n重启服务，并确认 `.env` 没有覆盖成：\n\n```text\nENABLE_EVALUATION_API=false\n```\n\n### `/health` 显示 `milvus_unavailable`？\n\nWindows 本地 MVP 可以接受。只有上传文档后的完整向量检索需要 Docker Milvus。\n\n## 为什么这个仓库不只是聊天框\n\n大多数 RAG demo 优化的是“能回答”。StuckToShip 优化的是“能推进学习”。\n\n它真正关心的不是一段漂亮话，而是：\n\n- 我到底卡在哪？\n- 哪段课程、哪个代码文件、哪条报错方案支持这个回答？\n- 我下一步应该试什么？\n- 证据不足时，助教应该拒答什么？\n- 检索、prompt 或路由改动之后，系统到底变好还是变差？\n\n如果你想做一个看起来像认真工程项目的 RAG 作品集，而不是又一个套壳聊天框，可以从这里开始。\n"}}}}