# langchain-rag

**Repository Path**: happy_source/langchain-rag

## Basic Information

- **Project Name**: langchain-rag
- **Description**: 基于 LangChain  RAG 的学习笔记管理助手，支持笔记的创建、更新、删除、检索和基于笔记内容的智能问答。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-25
- **Last Updated**: 2026-05-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 学习笔记智能助手

基于 LangChain + RAG 的学习笔记管理助手，支持笔记的创建、更新、删除、检索和基于笔记内容的智能问答。

## 功能特性

- **笔记管理** — 通过自然语言创建、更新、删除笔记，支持标签分类
- **RAG 智能问答** — 基于本地笔记内容检索增强生成，回答有据可依
- **多轮对话** — Agent 持有对话记忆，支持上下文连续问答
- **双模式运行** — Web 界面（Gradio）和命令行界面

## 技术栈

| 组件 | 说明 |
|---|---|
| LangChain + LangGraph | Agent 构建、工具调用、RAG 链 |
| ChromaDB | 本地向量数据库 |
| SiliconFlow (DeepSeek) | LLM 与 Embedding 模型 |
| Gradio | Web 聊天界面 |
| Pydantic | 数据模型校验 |

## 项目结构

```
langchain-rag/
├── app.py                  # Gradio Web 界面入口
├── cli.py                  # 命令行交互入口
├── note_assistant/
│   ├── agent.py            # Agent 创建与配置
│   ├── chains.py           # RAG 检索链、向量库构建
│   ├── config.py           # 全局配置与环境变量
│   ├── models.py           # Pydantic 数据模型
│   ├── tools.py            # Agent 工具（CRUD + 问答）
│   └── streaming.py        # 流式输出解析
├── notes/                  # 笔记存储目录（Markdown）
├── vectorstore/            # ChromaDB 向量库持久化目录
├── static/images/          # 聊天头像资源
└── pyproject.toml
```

## 快速开始

### 1. 环境要求

- Python >= 3.11
- [uv](https://docs.astral.sh/uv/) 包管理器

### 2. 安装依赖

```bash
uv sync
```

### 3. 配置环境变量

复制示例文件并填入你的 API Key：

```bash
cp .env.example .env
```

`.env` 文件内容：

```env
SILICONFLOW_API_KEY=your siliconflow key here
SILICONFLOW_MODEL=deepseek-ai/DeepSeek-V3.1-Terminus
SILICONFLOW_EMBEDDING_MODEL=BAAI/bge-large-zh-v1.5
SILICONFLOW_BASE_URL=https://api.siliconflow.cn/v1

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=your-api-key
LANGSMITH_PROJECT=note-assistant
```

> [SiliconFlow](https://siliconflow.cn/) 提供 LLM 和 Embedding 模型的 API 服务，需要注册获取 Key。

### 4. 运行

**Web 界面：**

```bash
uv run app.py
```

浏览器访问 `http://127.0.0.1:7860`。

**命令行界面：**

```bash
uv run cli.py
```

## 开发指南

### 本地开发

```bash
# 安装依赖（含开发依赖）
uv sync

# 启动 Web 开发服务器
uv run app.py

# 或使用命令行模式调试
uv run cli.py

# 单独测试 RAG 检索
uv run note_assistant/chains.py

# 单独测试工具函数
uv run note_assistant/tools.py
```

### 添加新工具

1. 在 `note_assistant/tools.py` 中用 `@tool` 装饰器定义新函数
2. 将函数加入 `ALL_TOOLS` 列表
3. 在 `note_assistant/agent.py` 的 `SYSTEM_PROMPT` 中补充使用说明

### 向量库管理

向量库在 `vectorstore/` 目录下自动持久化。当 `notes/` 中的文件发生变更时，下次提问会自动触发重建。如需手动清理：

```bash
rm -rf vectorstore/
```

下次启动后会自动重建。

## 部署

### Docker

```bash
# 构建镜像
docker build -t note-assistant .

# 运行
docker run -d -p 7860:7860 \
  --env-file .env \
  -v $(pwd)/notes:/app/notes \
  --name note-assistant \
  note-assistant
```

### Docker Compose

```bash
# 启动
docker compose up -d

# 查看日志
docker compose logs -f

# 停止
docker compose down
```

生产环境建议将 `server_name` 改为 `0.0.0.0` 以允许外部访问，可通过环境变量控制。

## 工作原理

1. **笔记管理** — Agent 通过工具函数直接读写 `notes/` 目录下的 Markdown 文件
2. **向量索引** — 笔记变动后自动重建 ChromaDB 向量库，使用 BGE 中文 Embedding 模型
3. **RAG 检索** — 用户提问时，先进行语义检索（支持查询改写 + 按笔记标题定向检索），再用检索结果作为上下文生成回答
4. **流式输出** — Web 和 CLI 均支持逐 token 流式响应