# llm-chat

**Repository Path**: bytesifter/llm-chat

## Basic Information

- **Project Name**: llm-chat
- **Description**: 这是一个大模型聊天demo
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-22
- **Last Updated**: 2026-04-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🧠 LLM Chat Demo - 高级对话系统

一个演示性质的 Python 对话系统，展示如何为大语言模型（LLM）添加**短期记忆**、**长期记忆**（Milvus 向量数据库）和**自动会话压缩**能力。项目使用 `uv` 管理依赖，采用现代化包结构（`src/` 布局），支持中文对话。

> **注意：这是一个演示项目**，主要用于展示 LLM 记忆增强的技术实现，适合学习和参考。

## ✨ 核心功能

- **三层记忆架构**：
  - **短期记忆**：保留最近对话的上下文，确保连贯性
  - **长期记忆**：基于 Milvus 向量数据库，支持语义检索和持久化存储
  - **会话压缩**：自动总结冗长对话，保留关键信息，节省 tokens
- **信息提取**：从对话中自动提取结构化信息（人名、兴趣、地点等）
- **模块化设计**：代码结构清晰，便于理解和扩展
- **中文优化**：提示词和界面针对中文对话优化
- **现代化工具链**：使用 `uv` 进行依赖管理，开发体验优秀

## 🚀 快速开始

### 1. 安装依赖
```bash
# 使用 uv 安装所有依赖（推荐）
uv sync
```

### 2. 环境配置
复制 `.env.example` 为 `.env` 并填写你的配置：
```bash
cp .env.example .env
```
编辑 `.env` 文件：
```env
# OpenAI 兼容 API 配置
API_KEY=sk-your-api-key-here
BASE_URL=https://api.deepseek.com
MODEL_NAME=deepseek-chat

# Milvus 配置（如需使用长期记忆）
MILVUS_HOST=192.168.56.120
MILVUS_PORT=19530
```

### 3. 启动 Milvus（可选）
长期记忆功能需要运行 Milvus 服务。如果你不需要长期记忆，可以跳过此步。
```bash
# 确保 Milvus 运行在配置的主机和端口
# 默认：192.168.56.120:19530
```

### 4. 运行对话系统
**方式一：使用交互式菜单**
```bash
uv run python run.py
```

**方式二：直接使用命令行工具**
```bash
# 演示模式（预设对话示例）
uv run llm-chat --demo

# 交互模式（终端实时对话）
uv run llm-chat --interactive --user-id your_username
```

**方式三：在 Python 代码中使用**
```python
from src.llm_chat.advanced_agent import AdvancedConversationAgent

# 创建对话代理
agent = AdvancedConversationAgent(user_id="test_user")

# 处理用户消息
response = agent.process_message("你好，我叫张伟，是一名软件工程师。")
print(response)
```

## 📁 项目结构

```
llm-chat/
├── src/                           # 源代码目录
│   └── llm_chat/                 # 主包
│       ├── __init__.py           # 包导出
│       ├── config.py             # 配置管理
│       ├── memory_types.py       # 数据结构和枚举
│       ├── short_term_memory.py  # 短期记忆管理
│       ├── long_term_memory.py   # Milvus 长期记忆
│       ├── conversation_compressor.py  # 会话压缩
│       ├── information_extractor.py    # 信息提取
│       ├── advanced_agent.py     # 高级对话代理（集成所有组件）
│       └── cli.py                # 命令行接口
├── tests/                        # 测试目录
│   └── test_semantic_search.py   # 语义搜索测试
├── run.py                        # 启动脚本（交互式菜单）
├── pyproject.toml                # 项目配置和依赖声明
├── uv.lock                       # 依赖锁文件
├── .env.example                  # 环境变量示例
└── README.md                     # 本文件
```

## 🔧 配置说明

主要配置位于 `src/llm_chat/config.py`，支持通过环境变量覆盖：

- **LLM API 配置**：
  - `API_KEY`: OpenAI 兼容 API 密钥
  - `BASE_URL`: API 基础地址
  - `MODEL_NAME`: 模型名称（默认：deepseek-chat）

- **Milvus 配置**：
  - `MILVUS_HOST`: Milvus 服务地址（默认：192.168.56.120）
  - `MILVUS_PORT`: Milvus 服务端口（默认：19530）
  - `MILVUS_COLLECTION_NAME_V2`: 集合名称（默认：advanced_conversation_memory_v2）

- **模型目录**：
  - `MODELS_DIR`: 本地模型存放路径（默认：D:\code\models）

- **记忆配置**：
  - `COMPRESSION_THRESHOLD`: 触发压缩的对话轮数（默认：10）
  - `EXTRACTION_INTERVAL`: 信息提取间隔（默认：3）
  - `SHORT_TERM_MAX_TURNS`: 短期记忆最大轮数（默认：20）
  - `SHORT_TERM_MAX_TOKENS`: 短期记忆最大 token 数（默认：4000）

## 🧪 运行测试

```bash
# 运行语义搜索测试
uv run python tests/test_semantic_search.py
```

## 📝 注意事项

1. **Milvus 服务**：长期记忆功能需要运行 Milvus（版本 2.6.11+），如不需要可禁用相关功能
2. **嵌入模型**：首次运行会自动下载 `paraphrase-multilingual-MiniLM-L12-v2` 模型（约 420MB）
3. **API 成本**：会话压缩和 embedding 生成会消耗 API tokens，请合理设置阈值
4. **隐私安全**：对话内容会发送到配置的 LLM API，请确保符合隐私政策
5. **离线运行**：模型下载后支持完全离线运行（设置环境变量 `TRANSFORMERS_OFFLINE=1`）

## 🔍 技术细节

### 长期记忆实现
- 使用 `paraphrase-multilingual-MiniLM-L12-v2` 模型生成 384 维语义嵌入向量
- 对话内容通过语义嵌入存入 Milvus 向量数据库
- 支持真正的语义检索（语义相似性匹配，非关键词匹配）
- 多语言支持（50+ 种语言），中文优化

### 会话压缩
当短期记忆达到阈值时，系统自动调用 LLM 对对话进行总结，保留关键信息，释放短期记忆空间。

### 信息提取
基于正则表达式模式匹配，自动从对话中提取结构化信息，用于记忆分类和检索。

## 🛠️ 开发指南

### 添加新的信息提取模式
编辑 `src/llm_chat/information_extractor.py` 中的 `PATTERNS` 字典，添加正则表达式和分类。

### 调整记忆策略
修改 `src/llm_chat/advanced_agent.py` 中的 `_should_compress()` 和 `_retrieve_long_term_memory()` 方法。

### 替换向量数据库
实现新的 `LongTermMemory` 类，保持相同的接口，然后在 `advanced_agent.py` 中替换。

## ❓ 常见问题

### Q: `learn_ai.egg-info` 目录是怎么产生的？
**A**: 这个目录是 `setuptools` 在构建或安装包时生成的。当运行 `uv build`、`uv run python`（可能会触发构建）等命令时，会自动创建该目录。

**解决方案**：
1. 将该目录添加到 `.gitignore`：
   ```gitignore
   *.egg-info/
   ```
2. 如果已经生成，可以安全删除：
   ```bash
   rm -rf learn_ai.egg-info
   ```
3. 该目录只包含包元数据，不会影响代码运行。

### Q: 如何在不安装的情况下运行代码？
**A**: 使用 `uv run python script.py` 或直接设置 `PYTHONPATH`：
```bash
# 方法一：使用 uv run
uv run python run.py

# 方法二：设置 PYTHONPATH
export PYTHONPATH=src:$PYTHONPATH
python run.py
```

### Q: 如何禁用长期记忆功能？
**A**: 如果不启动 Milvus 服务，长期记忆功能会自动回退到伪嵌入模式，保证系统可用性。

## 📄 许可证

MIT 许可证 - 自由使用、修改和分发。

---

**提示**：这是一个演示项目，适合学习和参考。生产环境使用请根据需求进行适当调整和测试。