# 1. 导入所需依赖库
# FastAPI：高性能异步Web框架，用于搭建API服务
from fastapi import FastAPI
# Pydantic：数据校验工具，用于定义请求体格式、自动校验参数
from pydantic import BaseModel
# httpx：异步HTTP客户端库，**专门用于异步代码中发送网络请求**（替代同步的requests库）
import httpx
# os：用于读取系统环境变量（安全存储API密钥，避免硬编码）
import os

# 2. 创建FastAPI应用实例
app = FastAPI()

# 3. 定义请求体数据模型（Pydantic模型）
# 作用：自动校验前端传入的JSON数据格式，确保必须包含content字段
class Question(BaseModel):
    # 前端传入的问题内容，字符串类型
    content: str

# 4. 定义【异步接口】
# @app.post：声明这是POST请求接口，访问路径为 /ask
# async def：异步函数，核心优势：处理请求时，等待AI接口响应的过程不会阻塞其他请求
@app.post("/ask")
async def ask(q: Question) -> dict:
    """
    异步AI问答接口
    :param q: 前端传入的问题参数（自动通过Pydantic校验）
    :return: 包含AI回答的字典
    """
    # 异步上下文管理器：创建异步HTTP客户端
    # 优势：发送请求时挂起当前任务，服务器可以处理其他用户的请求
    async with httpx.AsyncClient() as client:
        # 异步发送POST请求到DeepSeek AI接口
        # await：等待AI接口响应，期间不阻塞事件循环
        resp = await client.post(
            # AI接口地址
            url="https://api.deepseek.com/chat/completions",
            # 请求头：携带API密钥进行身份验证（从环境变量读取，更安全）
            headers={
                "Authorization": f"Bearer {os.getenv('DEEPSEEK_API_KEY')}"
            },
            # 请求体：AI模型所需的参数（模型名称+用户问题）
            json={
                "model": "deepseek-chat",
                "messages": [{"role": "user", "content": q.content}]
            },
            # 请求超时时间：30秒
            timeout=30
        )
    
    # 解析AI接口返回的JSON数据，提取回答内容
    reply = resp.json()["choices"][0]["message"]["content"]
    
    # 返回结果给前端
    return {"answer": reply}