# llm_chat

**Repository Path**: software-engineering-pre-project/llm_chat

## Basic Information

- **Project Name**: llm_chat
- **Description**: 大语言模型对话
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-11-02
- **Last Updated**: 2025-11-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LLM Chat

一个基于 **FastAPI + LangChain + LangGraph** 的多会话聊天服务，支持工具调用、自动摘要、Server-Sent Events (SSE) 流式输出，以及基于 `thread_id` 的多窗口记录管理。

## ✨ 核心特性

- 💬 **多窗口会话隔离**：任意数量的前端对话框可通过唯一 `thread_id` 复用上下文
- 🌊 **流式 / 非流式响应**：同一模型既能 SSE 推送也能一次性返回
- 🧰 **可扩展工具链**：内置 `web_search`、`current_time`、`get_exe_path`、`open_app`，可继续扩展
- 🧠 **自动摘要**：对话过长自动触发 summarize 节点，保留最近 4 条消息 + 摘要
- 💾 **持久化状态**：使用 `AsyncSqliteSaver` 将 LangGraph checkpoint 保存到 `configs/checkpoints.db`
- 📜 **完备接口文档**：`uv run generate_openapi.py` 即可生成 `doc/openapi.json`

## 🚀 快速上手

1. **安装依赖**
  ```bash
  uv sync
  ```

2. **配置环境变量 (.env)**
  ```env
  # LLM 配置
  LLM_MODEL=deepseek-chat
  LLM_BASE_URL=https://api.deepseek.com
  LLM_API_KEY=your-api-key-here
  LLM_TEMPERATURE=0.8
  LLM_MAX_TOKENS=1024

  # API 服务地址（供 client.py 调用）
  API_BASE_URL=http://127.0.0.1:30701

  # Tavily（可选，web_search 需要）
  TAVILY_API_KEY=your-tavily-api-key
  ```

3. **启动服务端**
  ```bash
  uv run server.py
  # 或者
  uvicorn server:app --host 127.0.0.1 --port 30701
  ```

4. **运行命令行客户端**
  ```bash
  uv run client.py
  ```

## 🧑‍💻 命令行客户端指令

客户端默认使用 `thread_id = terminal_thread`，可通过以下命令管理多会话：

| 指令 | 说明 |
|------|------|
| `/thread <id>` | 切换或创建新的线程（多窗口场景自定义 ID） |
| `/threads` | 列出数据库中存在的所有线程及最近 checkpoint |
| `/history` | 查看当前线程的摘要与全部对话（会自动过滤工具/摘要节点） |
| `/summary` | 仅查看当前线程的摘要（若尚未生成会提示） |
| *其他文本* | 以流式方式发送给模型，事件流自动打印 |

## 📡 API 概览

| 端点 | 方法 | 描述 |
|------|------|------|
| `/chat` | POST | 非流式聊天，返回完整文本 |
| `/chat/stream` | POST | SSE 流式聊天，事件类型：start/message/ping/end/error |
| `/summary` | POST | 获取指定 `thread_id` 的摘要 |
| `/threads` | GET | 枚举所有存在过的线程及最后一个 checkpoint |
| `/threads/{thread_id}/messages` | GET | 返回线程历史（含摘要，排除工具与 summarize 输出） |
| `/health` | GET | 健康检查 |

生成 OpenAPI 文档：
```bash
uv run generate_openapi.py
# 输出: doc/openapi.json
```

## 🌊 SSE 事件格式

`/chat/stream` 会产生以下事件（均为 `text/event-stream`）：

```
event: start
data: {"status": "connected", "thread_id": "tab-1"}

event: message
data: {"content": "你好", "thread_id": "tab-1"}

event: ping
data: {"status": "ping", "thread_id": "tab-1"}

event: end
data: {"status": "completed", "thread_id": "tab-1"}
```

错误情况下会发送 `event: error`，包含 `code` 与 `message`。

## ⚙️ 内置工具

| 工具 | 功能 |
|------|------|
| `web_search(query, max_results)` | 通过 Tavily 搜索资讯（需 `TAVILY_API_KEY`） |
| `current_time(fmt, tz)` | 返回指定时区的当前时间 |
| `get_exe_path(base_url)` | 向本地辅助服务查询可执行程序映射并缓存于临时目录 |
| `open_app(app_name, base_url)` | 调用本地辅助服务启动指定应用 |

在 `api/tools.py` 中可以新增自定义工具，再由 `server.py` 自动注入到模型。

## 🧠 会话与摘要机制

- 每个 `thread_id` 对应一份 LangGraph 状态，保存在 `configs/checkpoints.db`
- 当消息数 > 8 或 token 数 > 2000 时触发 summarize 节点，将旧消息折叠为摘要
- `/threads/{thread_id}/messages` 会返回：
  - `summary` / `has_summary`
  - 按时间排序的 `messages`（自动过滤 summarize/tool 节点，前端无需额外处理）

## 📁 项目结构

```
llm_chat/
├── api/
│   ├── graph.py          # LangGraph builder、状态流转逻辑
│   ├── models/           # Pydantic 请求/响应模型
│   ├── routes/           # FastAPI 路由（chat/stream/summary/threads/...）
│   └── tools.py          # 工具集合
├── client.py             # 命令行客户端（SSE 解析 + 多线程命令）
├── server.py             # FastAPI 应用入口，加载模型与工具
├── generate_openapi.py   # OpenAPI 增补脚本
├── configs/checkpoints.db# LangGraph SQLite 存储（运行时生成）
├── doc/openapi.json      # 生成的 OpenAPI 文档
├── pyproject.toml        # 依赖与构建配置
├── uv.lock               # uv 锁文件
└── .env / .env.example   # 模型、API Key 等配置
```

## 🔧 开发提示

- 所有命令均以 `uv run <script>` 方式执行，可自动激活虚拟环境
- 若需重置会话，删除 `configs/checkpoints.db` 即可，从头重新构建状态
- 在新增工具或变更模型参数后，重启 `server.py` 以让生命周期钩子重新绑定模型
- SSE 客户端可使用浏览器、curl 或任何支持 event-stream 的库；`client.py` 已提供示例

## 📜 许可证

MIT License

---
**当前版本**: v0.4.0 ｜ **更新日期**: 2025-11-29