# langchaindoc

**Repository Path**: phantom_2018/langchaindoc

## Basic Information

- **Project Name**: langchaindoc
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-07
- **Last Updated**: 2026-07-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 知识库问答系统

基于 **LangChain 1.x + Ollama + Chroma** 的本地知识库问答系统，支持文档管理、语义检索、RAG 问答、联网搜索、MCP 工具（天气/时间/POI/地理编码）、多对话管理。全部数据本地化，无需外网 API。

## 功能概览

| 功能 | 说明 |
|------|------|
| 📄 **文档管理** | 上传 txt/md/pdf/docx，自动切分入库，支持列出和删除 |
| 🔍 **语义检索** | 向量检索相关片段 + 相似度分数，支持按文档筛选 |
| 🤖 **RAG 问答** | 检索知识库 + LLM 生成带引用的回答，支持按文档筛选 |
| 💬 **AI 对话** | 与 LLM 直接对话，独立于知识库，支持流式输出 |
| 🌐 **联网搜索** | Bing 搜索引擎，自动获取最新资讯并供 LLM 回答 |
| 🛠 **MCP 工具** | 高德天气（含预报）、POI 搜索、地理编码、时间查询 |
| 🗂 **多对话** | 左侧会话列表，新建/切换/删除会话，记忆隔离 |
| 📎 **文件上传** | 对话中上传文档/图片，自动提取内容发给 AI 分析 |

## 技术栈

| 组件 | 选型 | 说明 |
|------|------|------|
| 框架 | LangChain 1.x | 官方拆分包：langchain-ollama / langchain-chroma |
| 大模型 | Ollama `qwen2.5:0.5b` | 对话生成（CPU 环境推荐） |
| 嵌入模型 | Ollama `bge-m3` | 中文召回率最佳；可换 `nomic-embed-text`（轻量） |
| 向量库 | Chroma | 本地持久化，支持 metadata 过滤 |
| 搜索引擎 | Bing (BeautifulSoup) | 国内可访问，无需 API Key |
| 地图 API | 高德地图 | 天气查询、POI 搜索、地理编码 |
| 前端 | 纯 HTML/CSS/JS | 单页应用，3 标签页布局 |
| API | FastAPI | Swagger 文档 + SSE 流式响应 |

## 快速开始

### 1. 准备 Ollama 与模型

```bash
# 拉取对话模型（CPU 环境推荐 qwen2.5:0.5b）
ollama pull qwen2.5:0.5b
# 若性能足够，可用 qwen2.5:7b 或 qwen3.5:4b
# 拉取嵌入模型
ollama pull bge-m3
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 配置环境

复制 `.env` 并根据需要修改：

```bash
# .env 关键配置
OLLAMA_CHAT_MODEL=qwen2.5:0.5b     # 对话模型
OLLAMA_EMBED_MODEL=bge-m3            # 嵌入模型
AMAP_API_KEY=your_key                # 高德地图 API Key（天气/POI 需要）
```

### 4. 启动服务

```bash
python main.py
```

启动后访问前端界面：**http://localhost:8000**

## 界面说明

### 1. 语义检索
- 输入查询文本，在知识库中检索最相关的文档片段
- 可指定文档范围（下拉选择器）
- 返回片段内容 + 相似度分数 + 来源文档名

### 2. RAG 问答
- 输入问题，检索知识库相关片段后由 LLM 生成回答
- 可指定文档范围
- 支持流式输出

### 3. AI 对话
- **左侧会话列表**：新建、切换、删除会话
- **启用高德工具**：勾选后天气/时间查询自动调用高德 API
- **文件上传**：📄 按钮上传文件，自动提取内容发给 AI
- **联网搜索**：包含"搜索/查找/最新/新闻"等关键词时自动联网

## API 一览

| 方法 | 路径 | 功能 |
|------|------|------|
| GET | `/health` | 健康检查 + 模型配置 + MCP 工具列表 |
| POST | `/documents/upload` | 上传文档 |
| GET | `/documents` | 列出所有文档 |
| DELETE | `/documents/{filename}` | 删除文档 |
| POST | `/search` | 语义检索（支持 source 过滤） |
| POST | `/ask` | RAG 问答（支持 source 过滤） |
| POST | `/chat` | AI 对话（带记忆） |
| POST | `/chat/stream` | AI 对话（SSE 流式） |
| POST | `/chat/with_tools` | 智能对话（自动联网 + 工具） |
| POST | `/chat/with_tools/stream` | 智能对话（SSE 流式） |
| POST | `/chat/upload` | 上传文件并提取内容 |
| POST | `/chat/clear` | 清空当前会话记忆 |
| GET | `/chat/conversations` | 列出所有会话 |
| POST | `/chat/conversations` | 创建新会话 |
| DELETE | `/chat/conversations/{id}` | 删除会话 |
| GET | `/tools/weather?city=北京` | 查询天气 |
| GET | `/tools/time?city=北京` | 查询时间 |

## 目录结构

```
aidoc/
├── main.py                 # FastAPI 入口
├── config.py               # 配置（Pydantic Settings）
├── mcp_server.py           # MCP 工具服务（时间/天气）
├── mcp_amap_server.py      # 高德 MCP 工具服务
├── requirements.txt
├── .env                    # 环境变量
├── app/
│   ├── embeddings.py       # 嵌入模型（单例）
│   ├── llm.py              # 对话模型（单例，支持流式）
│   ├── document_loader.py  # 文档加载与切分
│   ├── vector_store.py     # Chroma 向量库（单例，支持过滤）
│   ├── knowledge_base.py   # 知识库管理逻辑
│   ├── rag.py              # RAG 问答链
│   ├── web_search.py       # 联网搜索（Bing + DDG）
│   └── chat_memory.py      # 对话记忆（滑动窗口 10 轮）
└── static/
    └── index.html          # 前端单页应用
```

## 嵌入模型说明

| 模型 | 维度 | 体积 | 中文表现 | 适用场景 |
|------|------|------|----------|----------|
| **bge-m3**（默认） | 1024 | ~2GB | 最佳 | 中文知识库，召回率优先 |
| nomic-embed-text | 768 | ~270MB | 良好 | 配置有限，轻量优先 |

切换模型：修改 `.env` 的 `OLLAMA_EMBED_MODEL` → `ollama pull` 新模型 → 重启服务。
**注意**：切换嵌入模型后需重新上传文档（向量维度不兼容）。

## 注意事项

- CPU 环境推荐 `qwen2.5:0.5b`，`qwen3.5:4b` 需要足够内存
- 高德 MCP 工具随应用自动启动，无需单独运行
- 上传大文档（>10MB）时切分和向量化可能需要一些时间
- 会话记忆保留最近 10 轮对话