一个本地优先的开源实验室项目，提供从RAG流水线到多智能体编排的完整技术栈，帮助开发者系统学习和实践现代AI工程。

GroundedOS Lab：构建与评估落地AI系统的实践实验室\n\n## 项目定位：不只是又一个AI工具\n\n在大语言模型技术蓬勃发展的今天，GitHub上充斥着各种AI相关的开源项目——从简单的API封装到复杂的代理框架。然而，大多数项目要么过于简单，只能作为玩具演示；要么过于复杂，让学习者难以把握核心概念。\n\nGroundedOS Lab 选择了一条不同的道路。它不是一个产品化的AI应用，也不是一个仅供参考的示例代码库，而是一个实践学习实验室——一个让开发者能够亲手构建、观察和理解落地AI系统每个组件的完整环境。\n\n项目的核心定位可以概括为三个层次：\n1. 首要目标：作为实践学习实验室，手把手教学\n2. 次要目标：作为架构参考，展示RAG、智能体、评估、可观测性和安全如何在一个真实代码库中协同工作\n3. 第三目标：作为一个可用的本地AI助手（这是做好前两个目标的自然结果）\n\n## 核心理念：本地优先与渐进式构建\n\n### 本地优先哲学\n\nGroundedOS Lab 坚持"本地优先"的设计原则。这意味着：\n- 所有核心功能都可以在本地运行，无需依赖外部API\n- 支持本地模型执行（通过Transformers、Ollama等）\n- 可选的云服务集成（OpenAI、Anthropic等）作为补充而非必需\n\n这种设计不仅保护了用户隐私，也大大降低了实验成本，让开发者能够自由探索而无需担心API费用。\n\n### 渐进式学习路径\n\n项目采用分阶段（Phase）的渐进式开发模式，目前已完成0-3阶段的基础实现：\n\nPhase 0 - 数据基础 ✅ 已完成\n- 统一文档模式（SourceDocument、NormalizedDocument）\n- ETL流水线支持文本和PDF导入\n- 样本数据集注册\n\nPhase 1 - 核心RAG ✅ 已完成\n- 文档上传与索引\n- 分块、嵌入、存储完整流程\n- 基于检索的问答\n- Dev Mode输出（块ID、相关性分数、源元数据）\n\nPhase 2 - 检索质量 ✅ 已完成\n- 查询理解（重写、扩展、意图检测）\n- 混合检索（稠密+稀疏）\n- 重排序\n- 语义缓存\n- 成本追踪\n\nPhase 2b - 持久化记忆 ✅ 已完成\n- 跨会话的对话记忆\n- 会话级别的记忆隔离\n\nPhase 3 - 智能层 ✅ 已完成\n- DocumentQAAgent智能体\n- 工具调用与推理循环\n- 安全护栏（提示注入、PII、越狱等）\n- 评估框架（忠实度、相关性、召回率）\n\nPhase 4 - 实验室 🚧 进行中\n- 提示A/B测试\n- 模型基准测试\n- 嵌入可视化\n- 模型路由\n\n## 技术架构：清晰的分层设计\n\nGroundedOS Lab 采用Monorepo结构，清晰地划分了不同职责：\n\n### 应用层（apps/）\n\n- api/：基于NestJS的后端API服务器\n- web/：基于React + Vite的前端应用\n- worker/：异步工作器（预留）\n\n### 包层（packages/）\n\n| 包名 | 职责 |\n|------|------|\n| core | 共享类型、工具函数、基础抽象 |\n| rag | 完整RAG流水线（分块、嵌入、混合搜索、重排序） |\n| agents | 多智能体编排与工具调用 |\n| memory | 对话与长期记忆管理 |\n| model-routing | 模型路由逻辑（本地vs云端、成本感知） |\n| safety | 护栏、PII脱敏、越狱防御 |\n| observability | OpenTelemetry追踪、成本追踪、延迟指标 |\n| evals | 评估框架（RAGAS、自定义评分器） |\n| etl | 文档摄取与预处理流水线 |\n| experiment-toolkit | 批量提示测试、参数扫描 |\n| benchmarks | 本地vs云端模型基准测试 |\n| viz | 嵌入可视化（t-SNE/UMAP） |\n\n### 实验层（experiments/）\n\n包含独立的实验性项目，产出可后续集成到核心系统的构件：\n- fine-tuning/：全量微调\n- lora/：LoRA适配器训练\n- distillation/：知识蒸馏\n- quantization/：模型量化\n- jailbreak-defense/：红队测试与提示注入防御\n- bias-tests/：偏见评估\n\n## 核心产品循环\n\nGroundedOS Lab 的所有功能都围绕一个可观察的核心循环展开：\n\n\n上传文档\n ↓\n索引（分块 → 嵌入 → 存储）\n ↓\n提问\n ↓\n检索相关块\n ↓\n生成落地答案\n ↓\n显示来源 + Dev Mode元数据\n ↓\n评估质量（忠实度、相关性、延迟、成本）\n ↓\n追踪完整请求\n\n\n这个循环目前已经可以通过本地RAG、持久化索引、重排序、权衡指标和会话记忆完整运行。\n\n## Dev Mode：透明化的AI系统\n\nGroundedOS Lab 的一个独特功能是Dev Mode，它让开发者能够深入观察系统内部：\n\n- 检索到的块及其相关性分数\n- Token使用情况\n- 每个阶段的延迟\n- 模型路由决策\n- 落地来源\n\n这种透明性对于理解和调试AI系统至关重要，也是项目"学习实验室"定位的具体体现。\n\n## Lab Mode：实验与优化\n\n除了核心的RAG功能，项目还提供了丰富的实验工具：\n\n- 提示A/B测试：自动比较不同提示的效果\n- 越狱游乐场：测试系统的安全边界\n- 模型基准测试：对比本地与云端模型的性能\n- 嵌入可视化：通过t-SNE/UMAP查看嵌入空间\n- 成本分析：详细的成本追踪与优化建议\n\n## 快速开始\n\n项目要求 Node.js ≥ 20 和 npm ≥ 8。\n\nbash\n# 1. 安装依赖\nnpm install\n\n# 2. 对样本数据集进行RAG测试\nnpm run rag:smoke -- --dataset phase-0-smoke-text --query \"What does this command verify?\"\n\n# 3. 对自己的文件提问\nnpm run rag:ask -- --file datasets/samples/phase-0-smoke.txt --type text --query \"Your question\"\n\n# 4. 启动API服务器（端口3001）\nnpm run api:dev\n\n# 5. 启动Web界面（端口3000）\nnpm run web:dev\n\n\nCLI命令会输出JSON格式的响应，包含查询、落地答案、检索到的块ID、分数、源元数据和偏移量。\n\n## 目标受众\n\nGroundedOS Lab 为以下人群设计：\n\n| 受众 | 获得价值 |\n|------|----------|\n| AI/ML工程师 | 结构化Monorepo，用于实验RAG、智能体、评估和安全 |\n| 后端工程师 | LLM驱动流水线、模型路由、可观测性、异步工作器的实践机会 |\n| 学生与研究者 | 将概念（嵌入、CoT、护栏）直接映射到工作代码的学习路径 |\n| 技术领导者 | 包含成本追踪、评估和安全层的落地AI系统参考架构 |\n\n## 学习资源\n\n项目提供了丰富的学习材料：\n\n- 概念文档（docs/concepts/）：每个AI概念的详细解释，链接到具体代码\n- 架构决策记录（docs/adr/）：解释系统为何如此构建\n- 学习路径（docs/study-tracks/）：按主题组织的引导式学习路线\n - 路径1：LLM基础\n - 路径2：多模态与智能体\n - 路径3：开源生态\n - 路径4：评估与对比\n - 路径5：高级RAG\n - 路径6：微调与适配\n - 路径7：自主AI系统\n\n## 技术栈选择\n\n### 当前栈（已运行）\n\n| 层级 | 技术 | 说明 |\n|------|------|------|\n| API服务器 | Node.js + NestJS | 已迁移至NestJS，见ADR-001 |\n| Web | React 19 + Vite + TypeScript | 现代前端技术栈 |\n| 存储 | 本地JSON文件 | 位于.groundedos/目录 |\n| 嵌入 | api-lexical（内置） | 默认，无需外部服务 |\n| 检索 | 内存混合搜索 | 无需外部向量数据库 |\n\n### 目标栈（逐步引入）\n\n| 层级 | 技术 | 计划阶段 |\n|------|------|----------|\n| 数据库 | PostgreSQL | Phase 6 |\n| 向量数据库 | pgvector → Qdrant | Phase 6 |\n| 队列 | Redis + BullMQ | Phase 3+ |\n| 工作器 | Python（ML流水线） | Phase 3+ |\n| 可观测性 | OpenTelemetry + Grafana | Phase 6 |\n| 容器 | Docker + docker-compose | Phase 6 |\n\n## 项目哲学\n\nGroundedOS Lab 明确声明了它不是什么：\n\n- 不是LLM API的包装器\n- 不只是聊天界面\n- 不是玩具项目\n\n它的关注点是系统设计、可靠性和真实世界的AI工程。每个功能的存在都是为了教学，而非为了产品化。\n\n## 结语\n\nGroundedOS Lab 代表了AI教育工具的一种新范式。它不是试图用更简单的抽象来隐藏复杂性，而是邀请开发者直面复杂性，通过亲手构建每个组件来真正理解AI系统的工作原理。\n\n对于希望深入理解现代AI系统架构的开发者来说，这是一个宝贵的资源。它不仅提供了可运行的代码，更重要的是提供了一种系统性的学习方法——从基础概念到高级技术，从理论理解到工程实践。\n\n正如项目文档所言："这不是一个演示。这是一个用于理解生产环境中落地AI系统的实验室。"\n\n项目地址：https://github.com/IzaacBaptista/GroundedOS-Lab\n

GroundedOS Lab：构建与评估落地AI系统的实践实验室\n\n项目定位：不只是又一个AI工具\n\n在大语言模型技术蓬勃发展的今天，GitHub上充斥着各种AI相关的开源项目——从简单的API封装到复杂的代理框架。然而，大多数项目要么过于简单，只能作为玩具演示；要么过于复杂，让学习者难以把握核心概念。\n\nGroundedOS Lab 选择了一条不同的道路。它不是一个产品化的AI应用，也不是一个仅供参考的示例代码库，而是一个实践学习实验室——一个让开发者能够亲手构建、观察和理解落地AI系统每个组件的完整环境。\n\n项目的核心定位可以概括为三个层次：\n1. 首要目标：作为实践学习实验室，手把手教学\n2. 次要目标：作为架构参考，展示RAG、智能体、评估、可观测性和安全如何在一个真实代码库中协同工作\n3. 第三目标：作为一个可用的本地AI助手（这是做好前两个目标的自然结果）\n\n核心理念：本地优先与渐进式构建\n\n本地优先哲学\n\nGroundedOS Lab 坚持"本地优先"的设计原则。这意味着：\n- 所有核心功能都可以在本地运行，无需依赖外部API\n- 支持本地模型执行（通过Transformers、Ollama等）\n- 可选的云服务集成（OpenAI、Anthropic等）作为补充而非必需\n\n这种设计不仅保护了用户隐私，也大大降低了实验成本，让开发者能够自由探索而无需担心API费用。\n\n渐进式学习路径\n\n项目采用分阶段（Phase）的渐进式开发模式，目前已完成0-3阶段的基础实现：\n\nPhase 0 - 数据基础 ✅ 已完成\n- 统一文档模式（SourceDocument、NormalizedDocument）\n- ETL流水线支持文本和PDF导入\n- 样本数据集注册\n\nPhase 1 - 核心RAG ✅ 已完成\n- 文档上传与索引\n- 分块、嵌入、存储完整流程\n- 基于检索的问答\n- Dev Mode输出（块ID、相关性分数、源元数据）\n\nPhase 2 - 检索质量 ✅ 已完成\n- 查询理解（重写、扩展、意图检测）\n- 混合检索（稠密+稀疏）\n- 重排序\n- 语义缓存\n- 成本追踪\n\nPhase 2b - 持久化记忆 ✅ 已完成\n- 跨会话的对话记忆\n- 会话级别的记忆隔离\n\nPhase 3 - 智能层 ✅ 已完成\n- DocumentQAAgent智能体\n- 工具调用与推理循环\n- 安全护栏（提示注入、PII、越狱等）\n- 评估框架（忠实度、相关性、召回率）\n\nPhase 4 - 实验室 🚧 进行中\n- 提示A/B测试\n- 模型基准测试\n- 嵌入可视化\n- 模型路由\n\n技术架构：清晰的分层设计\n\nGroundedOS Lab 采用Monorepo结构，清晰地划分了不同职责：\n\n应用层（apps/）\n\n- api/：基于NestJS的后端API服务器\n- web/：基于React + Vite的前端应用\n- worker/：异步工作器（预留）\n\n包层（packages/）\n\n| 包名 | 职责 |\n|------|------|\n| core | 共享类型、工具函数、基础抽象 |\n| rag | 完整RAG流水线（分块、嵌入、混合搜索、重排序） |\n| agents | 多智能体编排与工具调用 |\n| memory | 对话与长期记忆管理 |\n| model-routing | 模型路由逻辑（本地vs云端、成本感知） |\n| safety | 护栏、PII脱敏、越狱防御 |\n| observability | OpenTelemetry追踪、成本追踪、延迟指标 |\n| evals | 评估框架（RAGAS、自定义评分器） |\n| etl | 文档摄取与预处理流水线 |\n| experiment-toolkit | 批量提示测试、参数扫描 |\n| benchmarks | 本地vs云端模型基准测试 |\n| viz | 嵌入可视化（t-SNE/UMAP） |\n\n实验层（experiments/）\n\n包含独立的实验性项目，产出可后续集成到核心系统的构件：\n- fine-tuning/：全量微调\n- lora/：LoRA适配器训练\n- distillation/：知识蒸馏\n- quantization/：模型量化\n- jailbreak-defense/：红队测试与提示注入防御\n- bias-tests/：偏见评估\n\n核心产品循环\n\nGroundedOS Lab 的所有功能都围绕一个可观察的核心循环展开：\n\n\n上传文档\n ↓\n索引（分块 → 嵌入 → 存储）\n ↓\n提问\n ↓\n检索相关块\n ↓\n生成落地答案\n ↓\n显示来源 + Dev Mode元数据\n ↓\n评估质量（忠实度、相关性、延迟、成本）\n ↓\n追踪完整请求\n\n\n这个循环目前已经可以通过本地RAG、持久化索引、重排序、权衡指标和会话记忆完整运行。\n\nDev Mode：透明化的AI系统\n\nGroundedOS Lab 的一个独特功能是Dev Mode，它让开发者能够深入观察系统内部：\n\n- 检索到的块及其相关性分数\n- Token使用情况\n- 每个阶段的延迟\n- 模型路由决策\n- 落地来源\n\n这种透明性对于理解和调试AI系统至关重要，也是项目"学习实验室"定位的具体体现。\n\nLab Mode：实验与优化\n\n除了核心的RAG功能，项目还提供了丰富的实验工具：\n\n- 提示A/B测试：自动比较不同提示的效果\n- 越狱游乐场：测试系统的安全边界\n- 模型基准测试：对比本地与云端模型的性能\n- 嵌入可视化：通过t-SNE/UMAP查看嵌入空间\n- 成本分析：详细的成本追踪与优化建议\n\n快速开始\n\n项目要求 Node.js ≥ 20 和 npm ≥ 8。\n\nbash\n1. 安装依赖\nnpm install\n\n2. 对样本数据集进行RAG测试\nnpm run rag:smoke -- --dataset phase-0-smoke-text --query \"What does this command verify?\"\n\n3. 对自己的文件提问\nnpm run rag:ask -- --file datasets/samples/phase-0-smoke.txt --type text --query \"Your question\"\n\n4. 启动API服务器（端口3001）\nnpm run api:dev\n\n5. 启动Web界面（端口3000）\nnpm run web:dev\n\n\nCLI命令会输出JSON格式的响应，包含查询、落地答案、检索到的块ID、分数、源元数据和偏移量。\n\n目标受众\n\nGroundedOS Lab 为以下人群设计：\n\n| 受众 | 获得价值 |\n|------|----------|\n| AI/ML工程师 | 结构化Monorepo，用于实验RAG、智能体、评估和安全 |\n| 后端工程师 | LLM驱动流水线、模型路由、可观测性、异步工作器的实践机会 |\n| 学生与研究者 | 将概念（嵌入、CoT、护栏）直接映射到工作代码的学习路径 |\n| 技术领导者 | 包含成本追踪、评估和安全层的落地AI系统参考架构 |\n\n学习资源\n\n项目提供了丰富的学习材料：\n\n- 概念文档（docs/concepts/）：每个AI概念的详细解释，链接到具体代码\n- 架构决策记录（docs/adr/）：解释系统为何如此构建\n- 学习路径（docs/study-tracks/）：按主题组织的引导式学习路线\n - 路径1：LLM基础\n - 路径2：多模态与智能体\n - 路径3：开源生态\n - 路径4：评估与对比\n - 路径5：高级RAG\n - 路径6：微调与适配\n - 路径7：自主AI系统\n\n技术栈选择\n\n当前栈（已运行）\n\n| 层级 | 技术 | 说明 |\n|------|------|------|\n| API服务器 | Node.js + NestJS | 已迁移至NestJS，见ADR-001 |\n| Web | React 19 + Vite + TypeScript | 现代前端技术栈 |\n| 存储 | 本地JSON文件 | 位于.groundedos/目录 |\n| 嵌入 | api-lexical（内置） | 默认，无需外部服务 |\n| 检索 | 内存混合搜索 | 无需外部向量数据库 |\n\n目标栈（逐步引入）\n\n| 层级 | 技术 | 计划阶段 |\n|------|------|----------|\n| 数据库 | PostgreSQL | Phase 6 |\n| 向量数据库 | pgvector → Qdrant | Phase 6 |\n| 队列 | Redis + BullMQ | Phase 3+ |\n| 工作器 | Python（ML流水线） | Phase 3+ |\n| 可观测性 | OpenTelemetry + Grafana | Phase 6 |\n| 容器 | Docker + docker-compose | Phase 6 |\n\n项目哲学\n\nGroundedOS Lab 明确声明了它不是什么：\n\n- 不是LLM API的包装器\n- 不只是聊天界面\n- 不是玩具项目\n\n它的关注点是系统设计、可靠性和真实世界的AI工程。每个功能的存在都是为了教学，而非为了产品化。\n\n结语\n\nGroundedOS Lab 代表了AI教育工具的一种新范式。它不是试图用更简单的抽象来隐藏复杂性，而是邀请开发者直面复杂性，通过亲手构建每个组件来真正理解AI系统的工作原理。\n\n对于希望深入理解现代AI系统架构的开发者来说，这是一个宝贵的资源。它不仅提供了可运行的代码，更重要的是提供了一种系统性的学习方法——从基础概念到高级技术，从理论理解到工程实践。\n\n正如项目文档所言："这不是一个演示。这是一个用于理解生产环境中落地AI系统的实验室。"\n\n项目地址：https://github.com/IzaacBaptista/GroundedOS-Lab\n