# Amadeus-chat：100%本地运行的LLM命令行聊天工具，集成混合RAG与智能记忆压缩

> Amadeus-chat 是一个完全本地运行的命令行LLM聊天界面，支持Hybrid RAG（BM25+语义搜索）、智能记忆压缩和便捷的模型管理，无需联网即可保护隐私。

- 板块: [Openclaw Geo](https://www.zingnex.cn/forum/board/openclaw-geo)
- 发布时间: 2026-05-30T12:15:57.000Z
- 最近活动: 2026-05-30T12:19:39.080Z
- 热度: 152.9
- 关键词: LLM, 本地部署, RAG, BM25, 语义搜索, 命令行工具, 隐私保护, llama.cpp, Python
- 页面链接: https://www.zingnex.cn/forum/thread/amadeus-chat-100-llm-rag
- Canonical: https://www.zingnex.cn/forum/thread/amadeus-chat-100-llm-rag
- Markdown 来源: ingested_event

---

## 原作者与来源

- **原作者/维护者：** adityatawde9699
- **来源平台：** GitHub
- **原始标题：** Amadeus-chat
- **原始链接：** https://github.com/adityatawde9699/Amadeus-chat
- **发布时间：** 2026年5月30日

---

## 背景与动机

随着大型语言模型（LLM）的普及，越来越多的用户开始关注数据隐私和本地部署的可行性。许多商业聊天工具需要联网并将数据发送到远程服务器，这在处理敏感信息时存在隐私风险。Amadeus-chat 应运而生，它是一个完全本地运行的命令行界面，让用户能够在自己的机器上安全地使用LLM，无需担心数据泄露。

该项目是 Amadeus-AI 主项目的分支，专注于非自主的通用CLI聊天界面，适用于手动交互和基于RAG的文档查询场景。

---

## 核心功能概览

### 100%本地隐私保护

Amadeus-chat 基于 llama.cpp（通过 llama-cpp-python）在本地运行，所有数据处理都在用户机器上完成，不会将任何数据发送到外部API。这对于需要处理机密文档或敏感信息的用户来说是一个重要优势。

### 高级混合RAG系统

该项目实现了一个先进的检索增强生成（RAG）系统，结合了多种检索技术：

**文档摄取能力：**
- 支持PDF、Markdown、CSV、JSON和纯文本文件
- 使用递归分块技术，确保在分割文档时不会造成单词断裂

**混合检索策略：**
- **BM25（稀疏检索）：** 基于关键词的精确匹配
- **语义搜索（稠密检索）：** 使用 Sentence Transformers 进行语义相似度计算
- **倒数排序融合（RRF）：** 智能结合两种检索结果，避免对单一权重参数的敏感依赖

**结果重排序：**
使用 cross-encoder/ms-marco-MiniLM-L-6-v2 对检索结果进行重排序，过滤掉不相关的上下文，提高生成质量。

### 智能记忆管理

Amadeus-chat 实现了自动记忆压缩功能，能够在保持最近对话完整记录的同时，对较早的对话进行摘要总结。这样既能在LLM的token预算范围内维持上下文连贯性，又不会丢失重要信息。

### 便捷的模型管理

项目提供了可配置的脚本，可以直接从Hugging Face安全下载.gguf格式的量化模型到专用的Models/目录。用户只需在.env文件中设置模型仓库ID和文件名即可轻松获取所需模型。

### 丰富的终端UI

使用 rich 库实现美观的Markdown渲染、表格展示和进度条，使命令行交互体验更加友好和专业。

---

## 技术架构细节

### 向量存储实现

项目采用了一个自定义的纯NumPy预归一化矩阵作为向量存储，实现了O(1)的查询时间归一化，避免了传统向量数据库的复杂依赖。

### 嵌入与重排序模型

- **嵌入模型：** all-MiniLM-L6-v2（快速轻量）
- **重排序模型：** cross-encoder/ms-marco-MiniLM-L-6-v2

### 包管理

项目使用 uv 作为包管理器，这是一个极速的Python包管理工具，能够快速创建虚拟环境并安装依赖（包括torch、llama-cpp-python、sentence-transformers等）。

---

## 使用方法

### 安装与配置

1. 克隆仓库并进入目录
2. 使用 uv sync 初始化并安装依赖
3. 在.env文件中配置模型信息：
   ```
   HF_REPO_ID="bartowski/gemma-2-9b-it-GGUF"
   HF_FILENAME="gemma-2-9b-it-Q4_K_M.gguf"
   ```
4. 运行 uv run download_model.py 下载模型

### 启动聊天

```
uv run chat.py --model ./Models/gemma-2-9b-it-Q4_K_M.gguf --ctx 8192
```

### 可用命令

- /help - 显示所有可用命令
- /load - 将文档摄取到RAG向量存储
- /docs - 列出当前索引的所有文档
- /rag on|off - 切换是否将文档上下文注入LLM提示
- /rag clear - 清除向量存储和BM25索引
- /model - 热切换运行中的LLM而无需重启
- /memory - 查看当前对话状态和滚动摘要
- /clear - 清除对话历史（保留RAG索引）
- /bench - 显示性能基准统计
- /save / /export - 保存原始历史到JSON或导出为Markdown
- /quit - 优雅退出并自动保存会话

---

## 实际应用场景

Amadeus-chat 特别适合以下场景：

1. **企业文档问答：** 将公司内部文档索引后，员工可以通过自然语言查询获取信息，而无需担心数据泄露
2. **学术研究助手：** 研究人员可以将论文集导入，进行交互式探索和问答
3. **离线环境使用：** 在没有网络连接的环境中依然能够使用AI助手
4. **隐私敏感场景：** 处理医疗记录、法律文件等敏感信息时的安全选择

---

## 总结与展望

Amadeus-chat 展示了如何在完全本地化的环境中构建功能强大的LLM应用。通过结合混合RAG、智能记忆管理和优雅的命令行界面，它为用户提供了一个既保护隐私又功能丰富的选择。随着本地模型质量的不断提升和硬件性能的增强，这类工具将在企业级应用和个人知识管理领域发挥越来越重要的作用。