# FastAPI 最小项目模板

一个最小可运行的 FastAPI 项目，包含健康检查与示例路由。

## 运行步骤

1) 创建虚拟环境并激活

```bash
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
python -m pip install -U pip
```

2) 安装依赖

```bash
pip install -r requirements.txt
```

3) 启动开发服务（热重载）

```bash
uvicorn app.main:app --reload --port 8000
```

4) 打开接口文档

- Swagger UI: http://127.0.0.1:8000/docs
- ReDoc: http://127.0.0.1:8000/redoc

5) 内网IP

192.168.244.164

## 项目结构

```
.
├── app
│   ├── __init__.py
│   ├── core
│   │   ├── __init__.py
│   │   └── config.py       # 环境配置（LLM_PROVIDER 等）
│   ├── api
│   │   ├── __init__.py
│   │   ├── deps.py         # 依赖注入（LLMService）
│   │   └── routes.py       # 路由（/api/ping, /api/llm/chat）
│   ├── providers
│   │   ├── __init__.py
│   │   ├── base.py         # Provider 协议定义
│   │   └── mock_provider.py# 本地回显 Provider
│   ├── schemas
│   │   ├── __init__.py
│   │   └── llm.py          # LLM 请求/响应模型
│   ├── services
│   │   ├── __init__.py
│   │   └── llm_service.py  # LLM 业务服务
│   └── main.py            # FastAPI 应用入口（/health）
├── requirements.txt        # 依赖
├── .gitignore
└── README.md
```

## LLM 业务模块

- 环境变量：
  - `LLM_PROVIDER`：默认 `mock`
  - `LLM_MODEL`：默认 `mock-echo-001`
  - `LLM_TEMPERATURE`：默认 `1.0`
  - `OPENAI_API_KEY`：如接入 OpenAI 时使用（目前示例未调用外部服务）

- 示例接口：`POST /api/llm/chat`

请求体示例：

```json
{
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "你好，今天上海天气如何？"}
  ],
  "model": "mock-echo-001",
  "temperature": 0.7
}
```

响应示例（mock 提供器）：

```json
{
  "content": "[mock] You said: 你好，今天上海天气如何？",
  "model": "mock-echo-001",
  "usage": {"prompt_tokens": 8, "completion_tokens": 7, "total_tokens": 15}
}
```

后续要接入真实大模型时，只需新增对应 Provider（如 `openai_provider.py`），在 `app/api/deps.py` 中根据 `LLM_PROVIDER` 切换实例即可。

## 常见扩展（可选）

- 配置管理：引入 `pydantic-settings` 并添加 `Settings` 类读取环境变量
- 日志：使用 `logging` 或 `structlog`
- 测试：新增 `pytest`，并添加 `tests/` 目录
- 代码质量：`ruff`/`black`/`mypy`，及 `pre-commit`
- 容器化：编写 `Dockerfile` 与 `docker-compose.yml`