# agentic-example

**Repository Path**: bytesifter/agentic-example

## Basic Information

- **Project Name**: agentic-example
- **Description**: agentic-example
- **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-05-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🧠 Agentic Example - 高级对话系统

一个演示性质的 Python 对话系统，展示如何为大语言模型（LLM）添加**短期记忆**和**长期记忆**（JSON文件持久化）能力。项目使用 `uv` 管理依赖，采用现代化包结构（`src/` 布局），支持中文对话，并提供FastAPI HTTP接口和Prometheus监控。

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

## ✨ 核心功能

- **双层记忆架构**：
  - **短期记忆**：保留最近对话的上下文，确保连贯性
  - **长期记忆**：基于 JSON 文件持久化，自动提取关键信息（人名、兴趣等）
- **FastAPI HTTP 接口**：提供 RESTful API 访问对话功能
- **Prometheus 监控**：暴露系统性能指标
- **中文优化**：提示词和界面针对中文对话优化
- **现代化工具链**：使用 `uv` 进行依赖管理

## 🚀 快速开始

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

### 2. 环境配置
复制 `.env.example` 为 `.env` 并填写你的配置：
```bash
# Linux/Mac
cp .env.example .env

# Windows
copy .env.example .env
```
编辑 `.env` 文件：
```env
API_KEY=sk-your-api-key-here
BASE_URL=https://api.deepseek.com
MODEL_NAME=deepseek-chat
```

### 3. 运行对话系统
**方式一：命令行工具**
```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)
```

**方式三：HTTP API服务（OpenAI兼容）**
```bash
# 启动API服务（默认端口8000）
uv run llm-chat --api

# 指定端口和主机
uv run llm-chat --api --port 8080 --host 127.0.0.1

# 后台模式运行
uv run llm-chat --api --daemon
```

API端点：
| 端点 | 说明 |
|------|------|
| `GET /` | API基本信息 |
| `POST /v1/chat/completions` | 聊天完成（OpenAI兼容，支持stream=true/false） |
| `GET /health` | 健康检查 |
| `GET /docs` | Swagger UI文档 |
| `GET /metrics` | Prometheus监控指标 |
| `POST /api/v1/chat` | ⏳ 旧版兼容（推荐使用 /v1/chat/completions） |

**非流式调用（stream=false，默认）：**
```bash
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "你好"}],
    "stream": false
  }'
```

**流式调用（stream=true，逐token SSE输出）：**
```bash
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'
```

**Python客户端调用：**
```python
import requests

BASE_URL = "http://localhost:8000"

# 非流式（完整JSON）
r = requests.post(f"{BASE_URL}/v1/chat/completions", json={
    "messages": [{"role": "user", "content": "你好"}],
    "stream": False
})
print(r.json()["choices"][0]["message"]["content"])

# 流式（逐token输出）
r = requests.post(f"{BASE_URL}/v1/chat/completions", json={
    "messages": [{"role": "user", "content": "你好"}],
    "stream": True
}, stream=True)
for line in r.iter_lines():
    if line:
        print(line.decode().strip())
```

> 通过 `X-User-Id` 请求头区分用户记忆（默认: "default"）。不带该头则共享同一份记忆。

## 📁 项目结构

```
agentic-example/
├── src/llm_chat/            # 主包
│   ├── __init__.py          # 包导出
│   ├── config.py            # 配置管理
│   ├── advanced_agent.py    # 对话代理（记忆增强核心）
│   ├── cli.py               # 命令行接口
│   ├── api.py               # FastAPI HTTP接口
│   └── service.py           # API服务管理
├── pyproject.toml           # 项目配置和依赖声明
├── .env.example             # 环境变量示例
└── README.md                # 本文件
```

## 🔧 配置说明

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `API_KEY` | OpenAI 兼容 API 密钥 | — |
| `BASE_URL` | API 基础地址 | https://api.deepseek.com |
| `MODEL_NAME` | 模型名称 | deepseek-chat |
| `API_HOST` | 服务绑定主机 | 0.0.0.0 |
| `API_PORT` | 服务端口 | 8000 |

## 📝 注意事项

1. **API 密钥**：需要有效的 OpenAI 兼容 API 密钥
2. **API 成本**：对话功能会消耗 API tokens
3. **隐私安全**：对话内容会发送到配置的 LLM API，请确保符合隐私政策
4. **长期记忆**：JSON 文件保存在 `memory/` 目录下，无需外部数据库

## ❓ 常见问题

### Q: 如何在不安装的情况下运行代码？
**A**: 使用 `uv run`：
```bash
uv run llm-chat --demo
```

### Q: 长期记忆是如何工作的？
**A**: 长期记忆使用 JSON 文件持久化，对话中提取的关键信息（如人名、兴趣）自动保存到 `memory/` 目录下。无需外部数据库服务。

### Q: `*.egg-info` 目录是怎么产生的？
**A**: 这是 `setuptools` 构建时自动生成的元数据目录，可以安全删除或加入 `.gitignore`。

### Q: 如何检查系统配置是否正确？
**A**: 运行 `uv run llm-chat --check` 检查 API 密钥和环境配置。

## 📄 许可证

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

---

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