pq-web-ai/README.md

FastAPI 最小项目模板

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

运行步骤

1) 创建虚拟环境并激活

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

2) 安装依赖

pip install -r requirements.txt

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

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

请求体示例：

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

响应示例（mock 提供器）：

{
  "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