266 lines
5.3 KiB
Markdown
266 lines
5.3 KiB
Markdown
# AI FastAPI Demo
|
||
|
||
一个基于 FastAPI 的 AI 调用示例工程，支持对话和工具调用。
|
||
|
||
## 功能特性
|
||
|
||
- **AI 对话接口**: 输入一段话，返回 AI 的回复
|
||
- **工具调用**: AI 可以调用工具（如获取当前时间）来回答问题
|
||
- **获取当前时间**: 提供直接获取当前时间的接口
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
ai_fastapi_project/
|
||
├── app/
|
||
│ ├── __init__.py
|
||
│ ├── main.py # FastAPI 主应用
|
||
│ ├── config.py # 配置管理
|
||
│ ├── api/
|
||
│ │ ├── __init__.py
|
||
│ │ └── chat.py # API 路由
|
||
│ ├── services/
|
||
│ │ ├── __init__.py
|
||
│ │ └── ai_service.py # AI 服务封装
|
||
│ └── tools/
|
||
│ ├── __init__.py
|
||
│ └── time_tool.py # 时间工具
|
||
├── requirements.txt # 依赖列表
|
||
├── .env.example # 环境变量示例
|
||
├── run.py # 启动脚本
|
||
└── README.md # 说明文档
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
cd ai_fastapi_project
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2. 配置环境变量
|
||
|
||
复制 `.env.example` 为 `.env` 并填写您的 OpenAI API Key:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env` 文件:
|
||
|
||
```
|
||
OPENAI_API_KEY=your_actual_api_key_here
|
||
```
|
||
|
||
### 3. 启动服务
|
||
|
||
根据您的使用场景选择合适的启动方式：
|
||
|
||
**方式 1: 普通运行（推荐）**
|
||
```bash
|
||
python run.py
|
||
```
|
||
|
||
**方式 2: PyCharm 调试模式**
|
||
```bash
|
||
python run_debug.py
|
||
```
|
||
或在 PyCharm 中右键 `run_debug.py` → Debug 'run_debug'
|
||
|
||
**方式 3: 开发模式（带热重载）**
|
||
```bash
|
||
python run_dev.py
|
||
```
|
||
代码修改后自动重载，适合开发调试
|
||
|
||
**方式 4: 命令行启动**
|
||
```bash
|
||
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
服务将在 `http://0.0.0.0:8000` 启动。
|
||
|
||
### 4. 访问 API 文档
|
||
|
||
启动服务后，访问以下地址查看 API 文档:
|
||
|
||
- Swagger UI: http://localhost:8000/docs
|
||
- ReDoc: http://localhost:8000/redoc
|
||
|
||
## API 接口说明
|
||
|
||
### 1. AI 对话接口
|
||
|
||
**POST** `/api/v1/chat`
|
||
|
||
请求示例:
|
||
|
||
```json
|
||
{
|
||
"message": "你好，请介绍一下自己",
|
||
"system_prompt": "你是一个友好的AI助手",
|
||
"history": []
|
||
}
|
||
```
|
||
|
||
响应示例:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "对话成功",
|
||
"response": "你好！我是一个AI助手..."
|
||
}
|
||
```
|
||
|
||
### 2. 带工具调用的 AI 对话接口
|
||
|
||
**POST** `/api/v1/chat-with-tools`
|
||
|
||
AI 可以调用工具（如获取当前时间）来回答问题。
|
||
|
||
请求示例:
|
||
|
||
```json
|
||
{
|
||
"message": "现在几点了？"
|
||
}
|
||
```
|
||
|
||
响应示例:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "对话成功",
|
||
"response": "现在是2026年4月27日 15:30:45，星期一。"
|
||
}
|
||
```
|
||
|
||
### 3. 获取当前时间接口
|
||
|
||
**GET** `/api/v1/time`
|
||
|
||
直接获取当前时间信息。
|
||
|
||
响应示例:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"current_time": "2026-04-27 15:30:45",
|
||
"date": "2026-04-27",
|
||
"time": "15:30:45",
|
||
"year": 2026,
|
||
"month": 4,
|
||
"day": 27,
|
||
"hour": 15,
|
||
"minute": 30,
|
||
"second": 45,
|
||
"weekday": "Monday",
|
||
"weekday_cn": "星期一"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### Python 调用示例
|
||
|
||
```python
|
||
import httpx
|
||
import asyncio
|
||
|
||
async def chat_with_ai():
|
||
async with httpx.AsyncClient() as client:
|
||
# 普通对话
|
||
response = await client.post(
|
||
"http://localhost:8000/api/v1/chat",
|
||
json={"message": "你好"}
|
||
)
|
||
print(response.json())
|
||
|
||
# 带工具调用的对话
|
||
response = await client.post(
|
||
"http://localhost:8000/api/v1/chat-with-tools",
|
||
json={"message": "现在几点了？"}
|
||
)
|
||
print(response.json())
|
||
|
||
# 获取时间
|
||
response = await client.get("http://localhost:8000/api/v1/time")
|
||
print(response.json())
|
||
|
||
asyncio.run(chat_with_ai())
|
||
```
|
||
|
||
### cURL 调用示例
|
||
|
||
```bash
|
||
# 普通对话
|
||
curl -X POST "http://localhost:8000/api/v1/chat" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"message": "你好"}'
|
||
|
||
# 带工具调用的对话
|
||
curl -X POST "http://localhost:8000/api/v1/chat-with-tools" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"message": "现在几点了？"}'
|
||
|
||
# 获取时间
|
||
curl -X GET "http://localhost:8000/api/v1/time"
|
||
```
|
||
|
||
## 扩展工具
|
||
|
||
要添加新的工具，请在 `app/tools/time_tool.py` 中:
|
||
|
||
1. 定义工具函数
|
||
2. 定义工具的 OpenAI function calling schema
|
||
3. 在 `AVAILABLE_TOOLS` 字典中注册工具
|
||
|
||
示例:
|
||
|
||
```python
|
||
def my_new_tool(param1: str) -> Dict[str, Any]:
|
||
"""新工具函数"""
|
||
return {"success": True, "data": "result"}
|
||
|
||
def my_new_tool_schema() -> Dict[str, Any]:
|
||
"""工具 schema"""
|
||
return {
|
||
"type": "function",
|
||
"function": {
|
||
"name": "my_new_tool",
|
||
"description": "工具描述",
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"param1": {"type": "string", "description": "参数描述"}
|
||
},
|
||
"required": ["param1"]
|
||
}
|
||
}
|
||
}
|
||
|
||
# 注册工具
|
||
AVAILABLE_TOOLS["my_new_tool"] = {
|
||
"function": my_new_tool,
|
||
"schema": my_new_tool_schema
|
||
}
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
- FastAPI: 现代、快速的 Web 框架
|
||
- OpenAI: AI 模型调用
|
||
- Pydantic: 数据验证和设置管理
|
||
- Uvicorn: ASGI 服务器
|
||
|
||
## 许可证
|
||
|
||
MIT License
|