这是一条能在个人电脑上复现的最小实操线：读取两份虚构制度 Markdown，按标题和行切分，调用 Ollama /api/embed，把向量和元数据原子写入 JSON，再用余弦相似度召回，最后让 /api/chat 只根据带编号证据回答。数据只有教学用途，不包含真实公司制度；索引没有 ACL，不能用于生产。

代码在 examples/rag_demo.py，样例数据在 examples/data/，题目格式在 examples/eval.jsonl。目录不会保存模型、虚拟环境、索引或缓存。

1. 准备 Ollama

安装并启动本机 Ollama，然后拉取模型：

ollama pull embeddinggemma
ollama pull qwen3:4b

本课默认 embeddinggemma 做向量、qwen3:4b 做回答。Ollama 官方模型页当前给出的 embeddinggemma 示例使用 /api/embed，并说明它支持 100 多种语言，适合中文入门；显存更紧张可换 nomic-embed-text，更重视多语种召回可试 qwen3-embedding:0.6b。同一个索引只能使用同一个 embedding 模型，切换模型必须重建。

2. 命令行契约

在本目录运行（Python 3.11+，无 pip install）：

cd blog/docs/articles/rag/examples
python3 rag_demo.py ingest data /tmp/rag-index.json
python3 rag_demo.py ask /tmp/rag-index.json '午餐补贴是多少？'
python3 rag_demo.py ask /tmp/rag-index.json '访客进入办公区需要什么？' --retrieval-only

ingest <docs_dir> <index.json> 会全量重建索引：先扫描全部 .md，为每段保存 id、source、heading、text、vector，再用临时文件 os.replace 原子替换目标。删除或更新文件后重新 ingest 不会留下旧片段。空目录仍会生成空索引。

ask <index.json> <question> 返回 JSON：answer 是模型回答，evidence 是 {id, source, heading, text, score} 数组。默认最多 3 条，低于 --min-score 0.2 的片段被丢弃；没有证据时固定拒答“没有足够证据回答。”，不会调用聊天模型。--retrieval-only 只看召回，适合离线学习和调阈值。--embed-model、--chat-model、--top-k、--url、--timeout 可显式覆盖默认值。

3. 看懂数据和答案

样例 Markdown 只包含虚构的午餐补贴、请假、密码和访客制度。每个证据编号在提示词中形如 [E1]，要求模型在结论中引用；终端输出的 evidence 同时保留相对路径和标题，便于人工回溯。评估题 JSONL 每行一个对象：

{"question":"午餐补贴是多少？","answer_contains":"30 元","evidence_source":"data/hr-policy.md"}

answer_contains 是人工或脚本检查的关键短语，evidence_source: null 表示这道题应拒答。真实项目还应评估 Recall@K、引用覆盖率、拒答质量和延迟。

4. 测试与排错

python3 -m unittest discover -s tests -v

测试使用伪造的 Ollama 对象，不声称真实模型调用通过；覆盖召回排序、引用、无证据拒答、空索引、模型不匹配、删除后重建和原子 JSON 写入。真实调用失败时脚本会报告服务/模型错误；请先确认 curl http://localhost:11434/api/tags 可访问，并确认模型名称拼写。若更换 embedding 模型后看到“索引模型是 …”错误，使用新模型重新 ingest。

5. 练习和边界

这是教学规模：几份 Markdown、线性扫描、JSON 全量载入，适合观察每一步，不适合多人、百万文档或敏感数据。它没有用户认证、ACL、加密、审计、增量更新或 prompt 注入防护；不要把真实员工资料放入样例目录。

后续练习可以把 retrieve 替换成 Qdrant 集合，给 payload 加部门/版本权限过滤，再把关键词 BM25 与向量分数做混合召回；先保留本课的 source、证据编号和拒答测试，确保迁移后答案仍可追溯。