132 lines
5.2 KiB
Markdown
132 lines
5.2 KiB
Markdown
# AI 助手项目
|
||
|
||
这是一个基于 Google Gemini API 构建的 AI 助手项目，旨在提供一个交互式的聊天界面，支持多轮对话、记忆管理和可配置的系统指令。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
.
|
||
├── app.py # 主应用程序入口，处理后端逻辑和API路由
|
||
├── config.ini # 配置文件，用于存储API密钥、模型设置、文件路径等
|
||
├── config.py # 配置加载和管理模块
|
||
├── file_manager.py # 文件操作工具，用于读写JSON、管理目录等
|
||
├── gemini_client.py # Gemini API 客户端，处理与Google Gemini API的交互
|
||
├── memory_manager.py # 记忆管理模块，处理短期和长期记忆的存储与检索
|
||
├── README.md # 项目说明文件
|
||
├── requirements.txt # Python依赖列表
|
||
├── utils.py # 常用工具函数，如日志配置、时间处理等
|
||
├── data/
|
||
│ ├── chat_logs/ # 存储聊天记录
|
||
│ ├── features/ # 存储角色特性（例如：default_role/features.json）
|
||
│ └── memories/ # 存储记忆数据（例如：default_memory/memory.json）
|
||
└── static/
|
||
├── index.html # 前端主页面
|
||
├── css/
|
||
│ ├── modern-style.css # 现代风格CSS
|
||
│ └── style.css # 主要CSS样式
|
||
├── js/
|
||
│ ├── api.js # 前端API调用逻辑
|
||
│ ├── app.js # 前端主应用逻辑
|
||
│ ├── ui_manager.js # 前端UI管理逻辑
|
||
│ └── lib/ # 前端第三方库
|
||
│ ├── marked.min.js # Markdown解析库
|
||
│ └── purify.min.js # HTML净化库
|
||
```
|
||
|
||
## 功能特性
|
||
|
||
* 多轮对话: 支持与AI进行连续的多轮对话，保持上下文。
|
||
* 记忆管理:
|
||
* 短期记忆: 存储最近的对话轮次，用于维持当前对话的连贯性。
|
||
* 长期记忆: 通过摘要和嵌入技术，将关键信息存储为长期记忆，以便在后续对话中检索和利用。
|
||
* 可配置性:
|
||
* 通过 `config.ini` 文件轻松配置 Gemini API 密钥、默认模型、上下文窗口大小、记忆保留轮次等。
|
||
* 支持从环境变量加载 `GEMINI_API_KEY`。
|
||
* 流式响应: 支持 Gemini API 的流式响应，提供更流畅的用户体验。
|
||
* 前端界面: 提供一个简洁的Web界面，方便用户与AI助手交互。
|
||
* 日志记录: 详细的日志记录，便于调试和问题追踪。
|
||
|
||
## 安装与运行
|
||
|
||
### 1. 克隆仓库
|
||
|
||
```bash
|
||
git clone https://github.com/your-username/your-repo-name.git
|
||
cd your-repo-name
|
||
```
|
||
(请将 `your-username/your-repo-name.git` 替换为实际的仓库地址)
|
||
|
||
### 2. 创建并激活虚拟环境 (推荐)
|
||
|
||
```bash
|
||
python -m venv venv
|
||
# Windows
|
||
.\venv\Scripts\activate
|
||
# macOS/Linux
|
||
source venv/bin/activate
|
||
```
|
||
|
||
### 3. 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 4. 配置 API 密钥
|
||
|
||
在项目根目录下找到 `config.ini` 文件。
|
||
将 `[API]` 部分的 `GEMINI_API_KEY` 替换为你的 Google Gemini API 密钥。
|
||
|
||
```ini
|
||
[API]
|
||
GEMINI_API_KEY = YOUR_GEMINI_API_KEY_HERE
|
||
```
|
||
或者，你可以设置环境变量 `GEMINI_API_KEY`。环境变量的优先级高于 `config.ini` 文件中的配置。
|
||
|
||
### 5. 运行应用程序
|
||
|
||
```bash
|
||
python app.py
|
||
```
|
||
|
||
应用程序将在本地启动一个Web服务。通常，你可以在浏览器中访问 `http://127.0.0.1:5000` 来使用AI助手。
|
||
|
||
## 配置说明
|
||
|
||
项目的主要配置通过 `config.ini` 文件管理。以下是各个配置项的详细说明：
|
||
|
||
### [API] 部分
|
||
|
||
* `gemini_api_base_url`: Gemini API 的基础 URL。如果使用代理或自定义端点，请修改此项。
|
||
* `gemini_api_key`: 你的 Google Gemini API 密钥。建议通过环境变量 `GEMINI_API_KEY` 设置，优先级更高。
|
||
* `default_gemini_model`: 默认使用的 Gemini 模型，例如 `models/gemini-2.0-flash`。
|
||
* `memory_update_model`: 用于记忆更新（摘要和嵌入）的 Gemini 模型。
|
||
|
||
### [Application] 部分
|
||
|
||
* `context_window_size`: 短期记忆中保留的对话轮次数量，用于维持当前对话的上下文。
|
||
* `memory_retention_turns`: 长期记忆更新的频率，每隔多少轮对话进行一次记忆摘要和存储。
|
||
* `max_short_term_events`: 短期记忆中最大事件（消息）数量。
|
||
* `features_dir`: 存储角色特性配置文件的目录路径。
|
||
* `memories_dir`: 存储长期记忆数据文件的目录路径。
|
||
* `chat_logs_dir`: 存储聊天记录文件的目录路径。
|
||
* `app_log_file_path`: 应用程序日志文件的路径。
|
||
|
||
### [Session] 部分
|
||
|
||
* `current_role_id`: 当前会话使用的角色ID。
|
||
* `current_memory_id`: 当前会话使用的记忆ID。
|
||
* `current_chat_log_id`: 当前会话的聊天记录ID。
|
||
|
||
## 使用说明
|
||
|
||
在Web界面中输入你的问题或指令，AI助手将根据你的输入和历史对话进行回复。
|
||
|
||
## 贡献
|
||
|
||
欢迎贡献！如果你有任何改进建议或发现bug，请提交Issue或Pull Request。
|
||
|
||
## 许可证
|
||
|
||
本项目采用 MIT 许可证。详见 `LICENSE` 文件 (如果存在)。
|