RAG 知识库应用项目

我们将直接调用 CNB 知识库 API（基于 CNB 知识库，只需上传 markdown 到指定 Git 仓库，即可自动构建知识库并提供 API 接口）

本项目还将使用 LangGraph 作为核心工作流引擎：

• LangGraph：用于构建复杂的 AI 工作流和状态管理
• 优势：支持多步骤推理、条件分支、循环处理等复杂逻辑
• 应用：非常适合实现 RAG 检索、多轮对话、深度研究等场景

本仓库当前代码实现的是「场景 1：基于当前的 Demo 仓库增强对话功能」，在原始 Demo 基础上做了以下增强：

• 多知识库切换：前端提供输入框，允许用户输入不同的 Git 仓库 slug（例如 cnb/docs、AI-learing-2025/knowledge 等），通过 CNB 知识库 API 动态切换检索的知识库。
• 引用来源角标展示：后端会在回答中返回来源文档的元数据（标题、path、url 等），前端会在 AI 回答中自动识别引用位置并渲染 数字角标，点击角标即可在新标签页打开对应的文档页面。
• 研究过程可视化（Activity Timeline）：对话过程中，前端会以时间线形式展示 LangGraph 的关键步骤（生成检索词、检索、反思、生成最终答案等），便于理解「它是怎么想的」。
• Thinking Process 折叠面板：当模型返回推理过程（reasoning_content）时，前端会在回答上方提供「Thinking Process」可展开区域，方便在需要时查看详细推理。

• 前端：React + Vite（源码位于 frontend/，入口 src/App.tsx）
• 后端：Python + LangGraph（源码位于 backend/，核心配置见 backend/src/agent/configuration.py）
• 知识库：CNB 知识库 API（通过 Git 仓库 markdown 文档自动构建）
• LLM：本地 Ollama，通过 OLLAMA_BASE_URL 访问（Docker 环境下默认指向 http://host.docker.internal:11434）
• 基础设施：Docker Compose（langgraph-api + langgraph-redis + langgraph-postgres）

• LANGSMITH_API_KEY：必需。用于 LangGraph Cloud 授权，docker-compose.yml 中的 langgraph-api 会从宿主机环境读取该变量。
  • 你可以在宿主机上通过如下方式设置：

    export LANGSMITH_API_KEY=your_langsmith_api_key
    

• OLLAMA_BASE_URL：可选，默认值：
  • 本地直接跑后端（非 Docker）：http://localhost:11434
  • Docker Compose 中已默认配置为：http://host.docker.internal:11434，用于访问宿主机上的 Ollama。
• CNB 相关配置（详见 backend/src/agent/configuration.py）：
  • cnb_repo_slug：默认使用 cnb/docs，前端实际查询时会被用户输入的仓库 slug 覆盖。
  • allowed_repos：后端内置了允许访问的仓库及其 token，例如：
    • cnb/docs
    • AI-learing-2025/knowledge
    • AI-learing-2025/project-1-knowledge-base
  • 如需新增知识库仓库，可在该配置中增加一条对应的 slug 与 token。

更详细的启动说明可参考仓库根目录下的 启动文档说明.md。

1. 准备 LangSmith API Key

   • 打开 https://smith.langchain.com → 进入 API Keys → 生成一个新的 API Key。
   • 在终端中执行：

     export LANGSMITH_API_KEY=your_api_key
     

2. 使用 Docker 一键启动后端（LangGraph API + Redis + Postgres）

   chmod +x start.sh      # 首次使用需要
   ./start.sh backend     # 等价于 docker compose up -d
   

   • 启动成功后，后端 API 将暴露在：http://localhost:8123

3. 启动前端开发服务器（本地体验最新 UI）

   ./start.sh frontend
   

   • 前端默认访问地址：http://localhost:5173/app/
   • 如果你只使用 Docker 构建的内置前端，也可以直接访问：http://localhost:8123/app/

4. 一键同时启动后端和前端（本地一站式体验）

   ./start.sh all
   

   • 脚本会在后台拉起 Docker 后端服务（Redis + Postgres + LangGraph API），并在前台启动前端开发服务器，适合本地开发时一条命令跑完整套。

5. 开始对话 & 切换知识库

   • 在页面顶部/输入区域，填写 知识库仓库 slug（例如 AI-learing-2025/project-1-knowledge-base）。
   • 在输入框中输入问题并发送，系统会：
     • 使用指定仓库对应的 CNB 知识库进行检索；
     • 利用 Ollama 模型结合检索结果生成回答；
     • 在回答中显示引用来源角标，点击可跳转到对应文档页面；
     • 在侧边显示检索 / 反思等步骤的时间线，以及可选的 Thinking Process 内容。