# langchain-chat

**Repository Path**: txsliwei/langchain-chat

## Basic Information

- **Project Name**: langchain-chat
- **Description**: tjliwei
langchain-chat
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-11
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LangChain Chat

> 基于 LangChain 的多轮会话系统（教学项目）

一个以学习企业级 Python 开发流程为目标的项目：从零开始，按步骤搭建一个具备多轮对话、用户管理、会话管理、预设系统、可插拔存储、多服务商模型切换的 AI 对话终端应用。

---

## 项目特性

- 多轮对话：基于消息历史的上下文保持，逐 token 流式输出
- 多服务商模型切换：支持通义千问、DeepSeek、OpenAI 等，运行时切换
- 用户管理：多用户隔离，数据互不可见
- 会话管理：创建、加载、重命名、删除、搜索历史消息、导出 Markdown
- 预设系统：内置角色预设加用户自定义预设
- 可插拔存储：SQLite / MySQL / File 三种后端，配置文件一键切换
- 对话搜索：按关键词搜索所有历史消息
- 结构化日志：JSON 格式，控制台加文件，按天轮转
- 全链路异步：LLM 调用、数据库、IO 全部 async/await
- 单元测试：pytest 覆盖核心模块

---

## 技术栈

| 类别 | 技术 |
|------|------|
| 语言 | Python 3.12（要求 3.10 及以上） |
| LLM 框架 | langchain 1.3.x、langchain-openai 1.3.x |
| 异步数据库 | aiosqlite、aiomysql |
| TUI 终端 | rich、prompt_toolkit |
| 配置校验 | pydantic、pydantic-settings |
| 包管理 | uv |
| 测试 | pytest、pytest-asyncio、pytest-cov |
| 日志 | Python logging（dictConfig） |

---

## 快速开始

### 1. 环境要求

- Python 3.12（要求 3.10 及以上）
- uv（包管理器）

```bash
uv --version          # 确认 uv 已安装
```

### 2. 克隆并配置

```bash
git clone https://gitee.com/txsliwei/langchain-chat.git
cd langchain-chat

# 配置环境变量
copy .env.example .env       # Windows
# cp .env.example .env       # macOS/Linux
```

编辑 .env，填入各服务商的 API Key：

```bash
# 通义千问
QWEN_API_KEY=sk-ws-你的通义key

# DeepSeek
DEEPSEEK_API_KEY=sk-你的deepseek-key

# OpenAI 代理
OPENAI_API_KEY=sk-你的openai代理key

# 默认模型（必须是 providers 里某个模型的 value）
DEFAULT_MODEL=qwen3.6-flash

# MySQL 密码（仅 MySQL 后端需要）
MYSQL_PASSWORD=root
```

### 3. 安装依赖并运行

```bash
uv sync                      # 创建虚拟环境 + 安装依赖
uv run python src/main.py    # 启动程序
```

---

## 配置说明

### 三层配置体系

| 层 | 文件 | 内容 | 进 Git |
|----|------|------|--------|
| 敏感配置 | .env | 各服务商 API Key | 否 |
| 业务配置 | config.yaml | 服务商分组、存储类型、超时等 | 是 |
| 日志配置 | config/logging.yaml | 日志格式与级别 | 是 |

### 服务商配置（config.yaml）

模型按服务商分组，每个服务商有自己的 base_url 和 api_key（Key 存 .env）：

```yaml
providers:
  - name: 通义千问
    base_url: https://xxx/compatible-mode/v1
    api_key_env: QWEN_API_KEY
    models:
      - name: 通义千问 Flash
        value: qwen3.6-flash
```

### 增加新模型

在 config.yaml 对应服务商的 models 列表里加一行即可，不需要改代码。

### 增加新服务商

1. .env 加一个 Key。
2. config.yaml 的 providers 加一块。两步完成。

### 切换存储后端

```yaml
# config.yaml
storage:
  type: sqlite      # sqlite | mysql | file
```

---

## 目录结构

```
langchain-chat/
├── .env.example                环境变量模板
├── .gitignore
├── config.yaml                 全局业务配置
├── config/
│   ├── presets.yaml            系统内置预设
│   └── logging.yaml            日志配置
├── pyproject.toml              项目元数据与依赖
├── uv.toml                     uv 镜像配置
├── README.md
├── data/                       运行时数据（gitignore）
├── logs/                       日志文件（gitignore）
├── src/                        源码（五层架构）
│   ├── main.py                 程序入口
│   ├── core/                   核心业务层
│   │   ├── config_manager.py
│   │   ├── user_manager.py
│   │   ├── preset_manager.py
│   │   ├── session_manager.py
│   │   └── chat_engine.py
│   ├── models/
│   │   └── schemas.py          Pydantic 数据模型
│   ├── storage/                存储层（可插拔）
│   │   ├── base.py             抽象基类
│   │   ├── factory.py          工厂模式
│   │   ├── sqlite_backend.py
│   │   ├── mysql_backend.py
│   │   └── file_backend.py
│   ├── interface/
│   │   └── ui_protocol.py      UI 接口定义
│   └── ui/tui/                 TUI 实现
│       ├── app.py
│       ├── chat_view.py
│       ├── menu_view.py
│       └── widgets.py
├── scripts/
│   ├── init_db.py              数据库初始化
│   └── test_chat_engine.py     对话引擎冒烟测试
├── tests/                      单元测试
│   ├── conftest.py
│   ├── test_storage.py
│   ├── test_user_manager.py
│   └── test_session_manager.py
├── examples/                   LLM 编程示例
│   ├── example1_http.py
│   ├── example2_openai_sdk.py
│   └── example3_langchain.py
└── docs/                       项目文档
```

---

## 使用说明

### 启动

```bash
uv run python src/main.py
```

### 主菜单功能

| 序号 | 功能 | 说明 |
|------|------|------|
| 1 | 用户管理 | 创建、切换、删除用户 |
| 2 | 会话管理 | 查看、加载、重命名、删除、查看记录、导出 Markdown |
| 3 | 预设管理 | 查看内置、新增、编辑、删除自定义预设 |
| 4 | 开始对话 | 多轮流式对话（核心功能） |
| 5 | 搜索对话 | 按关键词搜索历史消息 |
| 6 | 设置 | 查看/切换默认模型 |
| 7 | 关于 | 项目信息 |
| 8 | 退出 | 退出程序 |

### 对话中的命令

| 命令 | 功能 |
|------|------|
| 普通文字 | 发给 LLM 对话 |
| /exit | 退出对话 |
| /new | 新建会话 |
| /rename 标题 | 修改会话标题 |
| /model | 查看/切换模型 |
| /help | 显示帮助 |

### 运行测试

```bash
uv run pytest -v                              # 运行全部测试
uv run pytest --cov=src --cov-report=term     # 含覆盖率
```

---

## 开发步骤

项目按 15 个步骤推进，每步有对应的 Git tag：

| Tag | 内容 |
|-----|------|
| step-1-init | 项目初始化 |
| step-2-skeleton | 分层骨架 + TUI 菜单 |
| step-3-sqlite | SQLite 存储后端 |
| step-4-user-mgmt | 用户管理 |
| step-5-presets | 预设管理 |
| step-6-chat-engine | 对话引擎 |
| step-7-first-chat | 对话视图（核心里程碑） |
| step-8-session-mgmt | 会话管理完善 |
| step-9-search | 对话搜索 |
| step-10-export-switch | 导出 + 模型切换 |
| step-11-mysql | MySQL 存储后端 |
| step-12-logging-file | File 后端 + 日志 |
| step-13-tests | 单元测试 |
| step-14-docs-extend | 文档 + 架构审计 |
| step-15-envs | 多环境区分（规划中） |

回退到任意步骤：`git checkout step-X-xxx`

---

## 文档

- [需求说明文档](docs/需求说明文档.md)
- [实施步骤计划](docs/实施步骤计划.md)
- [需求变更与扩展登记](docs/需求变更与扩展登记.md)
- [架构设计文档](docs/architecture.md)
- [Git 命令与操作教学](docs/Git命令与操作教学.md)
- [uv 包管理器教学](docs/uv包管理器教学文档.md)
- 各步骤教学文档（Step1~Step13）

---

## 许可证

本项目为教学用途，暂未设定开源许可证。