77 lines
2.9 KiB
Markdown
77 lines
2.9 KiB
Markdown
# Simple Chat API
|
|
|
|
一个使用 FastAPI 和 DeepSeek API 的多轮 Agent 服务。每个会话的系统提示词、消息历史和工具调用过程保存在本地 JSON 文件中。
|
|
|
|
## 代码结构
|
|
|
|
- `routes.py`：集中定义所有 HTTP 路由。
|
|
- `auth.py`：校验 API key 白名单并识别当前用户。
|
|
- `schemas.py`：集中定义 API 请求和响应结构。
|
|
- `domain.py`：定义会话、消息和工具调用的持久化模型。
|
|
- `tools.py`：集中定义工具注册表、参数结构和工具函数。
|
|
- `service.py`：处理对话、Agent 循环和业务规则。
|
|
- `app.py`：创建 FastAPI 应用并管理生命周期。
|
|
|
|
## 启动
|
|
|
|
```bash
|
|
uv sync
|
|
cp .env.example .env
|
|
# 编辑 .env 并填写 DEEPSEEK_API_KEY
|
|
uv run uvicorn main:app --reload
|
|
```
|
|
|
|
服务默认运行在 `http://127.0.0.1:8000`，交互式 API 文档位于 `/docs`。
|
|
|
|
服务会自动加载项目根目录的 `.env`，已有系统环境变量优先级更高。可配置 `DEEPSEEK_BASE_URL`、`DEEPSEEK_MODEL`、`DEFAULT_SYSTEM_PROMPT`、`CHAT_DATA_DIR` 和工具调用限制，完整示例见 `.env.example`。第一版应只使用一个 Uvicorn worker。
|
|
|
|
所有业务接口都必须通过 `X-API-Key` 请求头提供访问密钥。白名单使用用户到密钥的 JSON 映射：
|
|
|
|
```text
|
|
API_KEY_WHITELIST={"11111111-1111-4111-8111-111111111111":"replace-with-a-secret-key"}
|
|
```
|
|
|
|
## 使用
|
|
|
|
创建会话：
|
|
|
|
```bash
|
|
curl -X POST http://127.0.0.1:8000/sessions \
|
|
-H 'X-API-Key: replace-with-a-secret-key' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"system_prompt":"你是一个简洁的中文助手。"}'
|
|
```
|
|
|
|
使用返回的 `session_id` 发送消息：
|
|
|
|
```bash
|
|
curl -X POST http://127.0.0.1:8000/sessions/SESSION_ID/messages \
|
|
-H 'X-API-Key: replace-with-a-secret-key' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"content":"你好，请记住我的名字是小明。"}'
|
|
```
|
|
|
|
API 返回及存储的每条消息都包含 UTC `created_at`。只有模型完整响应成功后，本轮消息才会写入会话历史。
|
|
|
|
模型可以按需调用服务端白名单工具：
|
|
|
|
- `get_current_time`：查询指定 IANA 时区的当前时间。
|
|
|
|
工具调用无需增加请求参数。服务端会执行工具并把结果返回模型，直到模型生成最终回答。发送消息接口通过 `tools_use` 返回本轮使用的工具名称，完整调用过程可通过历史接口查询；未调用工具时 `tools_use` 为空数组。
|
|
|
|
获取指定会话的完整历史：
|
|
|
|
```bash
|
|
curl http://127.0.0.1:8000/sessions/SESSION_ID/messages \
|
|
-H 'X-API-Key: replace-with-a-secret-key'
|
|
```
|
|
|
|
查询当前用户的累计 API 调用次数和 token 用量：
|
|
|
|
```bash
|
|
curl http://127.0.0.1:8000/usage \
|
|
-H 'X-API-Key: replace-with-a-secret-key'
|
|
```
|
|
|
|
每个会话 JSON 顶层保存所属 `user_id`、成功聊天次数及累计 token。`/usage` 会扫描并汇总当前用户的全部会话，不使用独立统计文件。创建会话、查询历史和查询用量不计入 `api_calls`。
|