xiaoxia-saas/apps/api/app/api/routes/ai.py

"""AI 相关接口 — 智能标题、智能素材匹配等.

基于豆包大模型的 AI 能力接口，未配置 API Key 时自动降级为本地模拟。
"""

from __future__ import annotations

from typing import List, Literal

from app.services.ai_service import TITLE_STYLES, generate_smart_titles, semantic_match_assets
from fastapi import APIRouter
from pydantic import BaseModel, Field

router = APIRouter()


# ── 请求/响应模型 ────────────────────────────────────────────────────────────


class GenerateTitlesRequest(BaseModel):
    """智能标题生成请求."""

    description: str = Field(..., min_length=1, max_length=500, description="视频内容描述")
    style: Literal["viral", "emotional", "informative"] = Field(
        default="viral",
        description="标题风格：viral爆款 / emotional情感 / informative信息",
    )
    count: int = Field(default=5, ge=3, le=10, description="生成数量，3-10个")


class GenerateTitlesResponse(BaseModel):
    """智能标题生成响应."""

    titles: List[str] = Field(..., description="生成的标题列表")
    style: str = Field(..., description="实际使用的风格")
    source: str = Field(..., description="来源：doubao 或 fallback")
    description: str = Field(..., description="原始描述")


class TitleStyleInfo(BaseModel):
    """标题风格信息."""

    key: str
    name: str
    description: str


# ── 素材语义匹配 ────────────────────────────────────────────────────────────


class AssetMatchItem(BaseModel):
    """待匹配素材项."""

    id: str = Field(..., description="素材ID")
    name: str = Field(default="", description="素材名称")
    tags: List[str] = Field(default_factory=list, description="标签列表")
    description: str = Field(default="", description="素材描述")


class SemanticMatchRequest(BaseModel):
    """语义匹配请求."""

    description: str = Field(..., min_length=1, max_length=500, description="目标视频内容描述")
    assets: List[AssetMatchItem] = Field(..., min_length=1, max_length=100, description="待匹配素材列表")
    top_k: int = Field(default=0, ge=0, le=100, description="返回前K个，0返回全部")


class SemanticMatchResultItem(AssetMatchItem):
    """匹配结果项."""

    match_score: float = Field(..., description="匹配度评分 0-1")
    match_reason: str = Field(..., description="匹配方式：doubao_semantic / fallback_keyword / fallback_default")


class SemanticMatchResponse(BaseModel):
    """语义匹配响应."""

    matches: List[SemanticMatchResultItem] = Field(..., description="按匹配度降序排列的素材列表")
    source: str = Field(..., description="来源：doubao / fallback")
    description: str = Field(..., description="原始描述")
    total: int = Field(..., description="输入素材总数")


# ── 路由 ────────────────────────────────────────────────────────────────────


@router.post("/titles/generate", response_model=GenerateTitlesResponse)
def generate_titles(request: GenerateTitlesRequest):
    """生成智能标题.

    根据视频描述生成指定风格的标题，支持爆款、情感、信息三种风格。
    未配置豆包 API Key 时自动降级为本地规则生成。
    """
    result = generate_smart_titles(
        description=request.description,
        style=request.style,
        count=request.count,
    )
    return GenerateTitlesResponse(**result)


@router.get("/titles/styles", response_model=List[TitleStyleInfo])
def list_title_styles():
    """获取支持的标题风格列表."""
    return [
        TitleStyleInfo(key=key, name=info["name"], description=info["description"])
        for key, info in TITLE_STYLES.items()
    ]


@router.post("/assets/match", response_model=SemanticMatchResponse)
def match_assets(request: SemanticMatchRequest):
    """智能素材语义匹配.

    根据用户描述，对素材列表做语义匹配并按匹配度排序。
    未配置豆包 API Key 时自动降级为关键词匹配。

    - 支持最多 100 个素材同时匹配
    - 返回 match_score (0-1)，按降序排列
    - top_k 可限制返回数量
    """
    # 转为 dict 传给服务层
    assets_dict = [asset.model_dump() for asset in request.assets]

    result = semantic_match_assets(
        description=request.description,
        assets=assets_dict,
        top_k=request.top_k,
    )

    return SemanticMatchResponse(
        matches=[SemanticMatchResultItem(**m) for m in result["matches"]],
        source=result["source"],
        description=result["description"],
        total=result["total"],
    )