ai-demo/README.md

# 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