Initial commit

src/api/admin/models/__init__.py

@@ -0,0 +1,16 @@
+"""
+模型管理相关 Admin API
+"""
+
+from fastapi import APIRouter
+
+from .catalog import router as catalog_router
+from .global_models import router as global_models_router
+from .mappings import router as mappings_router
+
+router = APIRouter(prefix="/api/admin/models", tags=["Admin - Model Management"])
+
+# 挂载子路由
+router.include_router(catalog_router)
+router.include_router(global_models_router)
+router.include_router(mappings_router)

src/api/admin/models/catalog.py

@@ -0,0 +1,432 @@
+"""
+统一模型目录 Admin API
+
+阶段一：基于 ModelMapping 和 Model 的聚合视图
+"""
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Set
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from sqlalchemy import func, or_
+from sqlalchemy.orm import Session, joinedload
+
+from src.api.base.admin_adapter import AdminApiAdapter
+from src.api.base.pipeline import ApiRequestPipeline
+from src.core.logger import logger
+from src.database import get_db
+from src.models.database import GlobalModel, Model, ModelMapping, Provider
+from src.models.pydantic_models import (
+    BatchAssignError,
+    BatchAssignModelMappingRequest,
+    BatchAssignModelMappingResponse,
+    BatchAssignProviderResult,
+    DeleteModelMappingResponse,
+    ModelCapabilities,
+    ModelCatalogItem,
+    ModelCatalogProviderDetail,
+    ModelCatalogResponse,
+    ModelPriceRange,
+    OrphanedModel,
+    UpdateModelMappingRequest,
+    UpdateModelMappingResponse,
+)
+from src.services.cache.invalidation import get_cache_invalidation_service
+from src.services.model.service import ModelService
+
+router = APIRouter(prefix="/catalog", tags=["Admin - Model Catalog"])
+pipeline = ApiRequestPipeline()
+
+
+@router.get("", response_model=ModelCatalogResponse)
+async def get_model_catalog(
+    request: Request,
+    db: Session = Depends(get_db),
+) -> ModelCatalogResponse:
+    adapter = AdminGetModelCatalogAdapter()
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
+
+
+@router.post("/batch-assign", response_model=BatchAssignModelMappingResponse)
+async def batch_assign_model_mappings(
+    request: Request,
+    payload: BatchAssignModelMappingRequest,
+    db: Session = Depends(get_db),
+) -> BatchAssignModelMappingResponse:
+    adapter = AdminBatchAssignModelMappingsAdapter(payload=payload)
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
+
+
+@dataclass
+class AdminGetModelCatalogAdapter(AdminApiAdapter):
+    """管理员查询统一模型目录
+
+    新架构说明：
+    1. 以 GlobalModel 为中心聚合数据
+    2. ModelMapping 表提供别名信息（provider_id=NULL 表示全局）
+    3. Model 表提供关联提供商和价格
+    """
+
+    async def handle(self, context):  # type: ignore[override]
+        db: Session = context.db
+
+        # 1. 获取所有活跃的 GlobalModel
+        global_models: List[GlobalModel] = (
+            db.query(GlobalModel).filter(GlobalModel.is_active == True).all()
+        )
+
+        # 2. 获取所有活跃的别名（含全局和 Provider 特定）
+        aliases_rows: List[ModelMapping] = (
+            db.query(ModelMapping)
+            .options(joinedload(ModelMapping.target_global_model))
+            .filter(
+                ModelMapping.is_active == True,
+                ModelMapping.provider_id.is_(None),
+            )
+            .all()
+        )
+
+        # 按 GlobalModel ID 组织别名
+        aliases_by_global_model: Dict[str, List[str]] = {}
+        for alias_row in aliases_rows:
+            if not alias_row.target_global_model_id:
+                continue
+            gm_id = alias_row.target_global_model_id
+            if gm_id not in aliases_by_global_model:
+                aliases_by_global_model[gm_id] = []
+            if alias_row.source_model not in aliases_by_global_model[gm_id]:
+                aliases_by_global_model[gm_id].append(alias_row.source_model)
+
+        # 3. 获取所有活跃的 Model 实现（包含 global_model 以便计算有效价格）
+        models: List[Model] = (
+            db.query(Model)
+            .options(joinedload(Model.provider), joinedload(Model.global_model))
+            .filter(Model.is_active == True)
+            .all()
+        )
+
+        # 按 GlobalModel ID 组织关联提供商
+        models_by_global_model: Dict[str, List[Model]] = {}
+        for model in models:
+            if model.global_model_id:
+                models_by_global_model.setdefault(model.global_model_id, []).append(model)
+
+        # 4. 为每个 GlobalModel 构建 catalog item
+        catalog_items: List[ModelCatalogItem] = []
+
+        for gm in global_models:
+            gm_id = gm.id
+            provider_entries: List[ModelCatalogProviderDetail] = []
+            capability_flags = {
+                "supports_vision": gm.default_supports_vision or False,
+                "supports_function_calling": gm.default_supports_function_calling or False,
+                "supports_streaming": gm.default_supports_streaming or False,
+            }
+
+            # 遍历该 GlobalModel 的所有关联提供商
+            for model in models_by_global_model.get(gm_id, []):
+                provider = model.provider
+                if not provider:
+                    continue
+
+                # 使用有效价格（考虑 GlobalModel 默认值）
+                effective_input = model.get_effective_input_price()
+                effective_output = model.get_effective_output_price()
+                effective_tiered = model.get_effective_tiered_pricing()
+                tier_count = len(effective_tiered.get("tiers", [])) if effective_tiered else 1
+
+                # 使用有效能力值
+                capability_flags["supports_vision"] = (
+                    capability_flags["supports_vision"] or model.get_effective_supports_vision()
+                )
+                capability_flags["supports_function_calling"] = (
+                    capability_flags["supports_function_calling"]
+                    or model.get_effective_supports_function_calling()
+                )
+                capability_flags["supports_streaming"] = (
+                    capability_flags["supports_streaming"]
+                    or model.get_effective_supports_streaming()
+                )
+
+                provider_entries.append(
+                    ModelCatalogProviderDetail(
+                        provider_id=provider.id,
+                        provider_name=provider.name,
+                        provider_display_name=provider.display_name,
+                        model_id=model.id,
+                        target_model=model.provider_model_name,
+                        # 显示有效价格
+                        input_price_per_1m=effective_input,
+                        output_price_per_1m=effective_output,
+                        cache_creation_price_per_1m=model.get_effective_cache_creation_price(),
+                        cache_read_price_per_1m=model.get_effective_cache_read_price(),
+                        cache_1h_creation_price_per_1m=model.get_effective_1h_cache_creation_price(),
+                        price_per_request=model.get_effective_price_per_request(),
+                        effective_tiered_pricing=effective_tiered,
+                        tier_count=tier_count,
+                        supports_vision=model.get_effective_supports_vision(),
+                        supports_function_calling=model.get_effective_supports_function_calling(),
+                        supports_streaming=model.get_effective_supports_streaming(),
+                        is_active=bool(model.is_active),
+                        mapping_id=None,  # 新架构中不再有 mapping_id
+                    )
+                )
+
+            # 模型目录显示 GlobalModel 的第一个阶梯价格（不是 Provider 聚合价格）
+            tiered = gm.default_tiered_pricing or {}
+            first_tier = tiered.get("tiers", [{}])[0] if tiered.get("tiers") else {}
+            price_range = ModelPriceRange(
+                min_input=first_tier.get("input_price_per_1m", 0),
+                max_input=first_tier.get("input_price_per_1m", 0),
+                min_output=first_tier.get("output_price_per_1m", 0),
+                max_output=first_tier.get("output_price_per_1m", 0),
+            )
+
+            catalog_items.append(
+                ModelCatalogItem(
+                    global_model_name=gm.name,
+                    display_name=gm.display_name,
+                    description=gm.description,
+                    aliases=aliases_by_global_model.get(gm_id, []),
+                    providers=provider_entries,
+                    price_range=price_range,
+                    total_providers=len(provider_entries),
+                    capabilities=ModelCapabilities(**capability_flags),
+                )
+            )
+
+        # 5. 查找孤立的别名（别名指向的 GlobalModel 不存在或不活跃）
+        orphaned_rows = (
+            db.query(ModelMapping.source_model, GlobalModel.name, func.count(ModelMapping.id))
+            .outerjoin(GlobalModel, ModelMapping.target_global_model_id == GlobalModel.id)
+            .filter(
+                ModelMapping.is_active == True,
+                ModelMapping.provider_id.is_(None),
+                or_(GlobalModel.id == None, GlobalModel.is_active == False),
+            )
+            .group_by(ModelMapping.source_model, GlobalModel.name)
+            .all()
+        )
+        orphaned_models = [
+            OrphanedModel(alias=row[0], global_model_name=row[1], mapping_count=row[2])
+            for row in orphaned_rows
+            if row[0]
+        ]
+
+        return ModelCatalogResponse(
+            models=catalog_items,
+            total=len(catalog_items),
+            orphaned_models=orphaned_models,
+        )
+
+
+@dataclass
+class AdminBatchAssignModelMappingsAdapter(AdminApiAdapter):
+    payload: BatchAssignModelMappingRequest
+
+    async def handle(self, context):  # type: ignore[override]
+        db: Session = context.db
+        created: List[BatchAssignProviderResult] = []
+        errors: List[BatchAssignError] = []
+
+        for provider_config in self.payload.providers:
+            provider_id = provider_config.provider_id
+            try:
+                provider: Provider = db.query(Provider).filter(Provider.id == provider_id).first()
+                if not provider:
+                    errors.append(
+                        BatchAssignError(provider_id=provider_id, error="Provider 不存在")
+                    )
+                    continue
+
+                model_id: Optional[str] = None
+                created_model = False
+
+                if provider_config.create_model:
+                    model_data = provider_config.model_data
+                    if not model_data:
+                        errors.append(
+                            BatchAssignError(provider_id=provider_id, error="缺少 model_data 配置")
+                        )
+                        continue
+
+                    existing_model = ModelService.get_model_by_name(
+                        db, provider_id, model_data.provider_model_name
+                    )
+                    if existing_model:
+                        model_id = existing_model.id
+                        logger.info("模型 %s 已存在于 Provider %s，复用现有模型",
+                            model_data.provider_model_name,
+                            provider.name,
+                        )
+                    else:
+                        model = ModelService.create_model(db, provider_id, model_data)
+                        model_id = model.id
+                        created_model = True
+                else:
+                    model_id = provider_config.model_id
+                    if not model_id:
+                        errors.append(
+                            BatchAssignError(provider_id=provider_id, error="缺少 model_id")
+                        )
+                        continue
+                    model = (
+                        db.query(Model)
+                        .filter(Model.id == model_id, Model.provider_id == provider_id)
+                        .first()
+                    )
+                    if not model:
+                        errors.append(
+                            BatchAssignError(
+                                provider_id=provider_id, error="模型不存在或不属于当前 Provider")
+                        )
+                        continue
+
+                # 批量分配功能需要适配 GlobalModel 架构
+                # 参见 docs/optimization-backlog.md 中的待办项
+                errors.append(
+                    BatchAssignError(
+                        provider_id=provider_id,
+                        error="批量分配功能暂时不可用，需要适配新的 GlobalModel 架构",
+                    )
+                )
+                continue
+
+            except Exception as exc:
+                db.rollback()
+                logger.error("批量添加模型映射失败（需要适配新架构）")
+                errors.append(BatchAssignError(provider_id=provider_id, error=str(exc)))
+
+        return BatchAssignModelMappingResponse(
+            success=len(created) > 0,
+            created_mappings=created,
+            errors=errors,
+        )
+
+
+@router.put("/mappings/{mapping_id}", response_model=UpdateModelMappingResponse)
+async def update_model_mapping(
+    request: Request,
+    mapping_id: str,
+    payload: UpdateModelMappingRequest,
+    db: Session = Depends(get_db),
+) -> UpdateModelMappingResponse:
+    """更新模型映射"""
+    adapter = AdminUpdateModelMappingAdapter(mapping_id=mapping_id, payload=payload)
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
+
+
+@router.delete("/mappings/{mapping_id}", response_model=DeleteModelMappingResponse)
+async def delete_model_mapping(
+    request: Request,
+    mapping_id: str,
+    db: Session = Depends(get_db),
+) -> DeleteModelMappingResponse:
+    """删除模型映射"""
+    adapter = AdminDeleteModelMappingAdapter(mapping_id=mapping_id)
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
+
+
+@dataclass
+class AdminUpdateModelMappingAdapter(AdminApiAdapter):
+    """更新模型映射"""
+
+    mapping_id: str
+    payload: UpdateModelMappingRequest
+
+    async def handle(self, context):  # type: ignore[override]
+        db: Session = context.db
+
+        mapping: Optional[ModelMapping] = (
+            db.query(ModelMapping).filter(ModelMapping.id == self.mapping_id).first()
+        )
+
+        if not mapping:
+            raise HTTPException(status_code=404, detail="映射不存在")
+
+        update_data = self.payload.model_dump(exclude_unset=True)
+
+        if "provider_id" in update_data:
+            new_provider_id = update_data["provider_id"]
+            if new_provider_id:
+                provider = db.query(Provider).filter(Provider.id == new_provider_id).first()
+                if not provider:
+                    raise HTTPException(status_code=404, detail="Provider 不存在")
+            mapping.provider_id = new_provider_id
+
+        if "target_global_model_id" in update_data:
+            target_model = (
+                db.query(GlobalModel)
+                .filter(
+                    GlobalModel.id == update_data["target_global_model_id"],
+                    GlobalModel.is_active == True,
+                )
+                .first()
+            )
+            if not target_model:
+                raise HTTPException(status_code=404, detail="目标 GlobalModel 不存在或未激活")
+            mapping.target_global_model_id = update_data["target_global_model_id"]
+
+        if "source_model" in update_data:
+            new_source = update_data["source_model"].strip()
+            if not new_source:
+                raise HTTPException(status_code=400, detail="source_model 不能为空")
+            mapping.source_model = new_source
+
+        if "is_active" in update_data:
+            mapping.is_active = update_data["is_active"]
+
+        duplicate = (
+            db.query(ModelMapping)
+            .filter(
+                ModelMapping.source_model == mapping.source_model,
+                ModelMapping.provider_id == mapping.provider_id,
+                ModelMapping.id != mapping.id,
+            )
+            .first()
+        )
+        if duplicate:
+            raise HTTPException(status_code=400, detail="映射已存在")
+
+        db.commit()
+        db.refresh(mapping)
+
+        cache_service = get_cache_invalidation_service()
+        cache_service.on_model_mapping_changed(mapping.source_model, mapping.provider_id)
+
+        return UpdateModelMappingResponse(
+            success=True,
+            mapping_id=mapping.id,
+            message="映射更新成功",
+        )
+
+
+@dataclass
+class AdminDeleteModelMappingAdapter(AdminApiAdapter):
+    """删除模型映射"""
+
+    mapping_id: str
+
+    async def handle(self, context):  # type: ignore[override]
+        db: Session = context.db
+
+        mapping: Optional[ModelMapping] = (
+            db.query(ModelMapping).filter(ModelMapping.id == self.mapping_id).first()
+        )
+
+        if not mapping:
+            raise HTTPException(status_code=404, detail="映射不存在")
+
+        source_model = mapping.source_model
+        provider_id = mapping.provider_id
+
+        db.delete(mapping)
+        db.commit()
+
+        cache_service = get_cache_invalidation_service()
+        cache_service.on_model_mapping_changed(source_model, provider_id)
+
+        return DeleteModelMappingResponse(
+            success=True,
+            message=f"映射 {self.mapping_id} 已删除",
+        )

src/api/admin/models/global_models.py

@@ -0,0 +1,292 @@
+"""
+GlobalModel Admin API
+
+提供 GlobalModel 的 CRUD 操作接口
+"""
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+from fastapi import APIRouter, Depends, Query, Request
+from sqlalchemy.orm import Session
+
+from src.api.base.admin_adapter import AdminApiAdapter
+from src.api.base.pipeline import ApiRequestPipeline
+from src.core.logger import logger
+from src.database import get_db
+from src.models.pydantic_models import (
+    BatchAssignToProvidersRequest,
+    BatchAssignToProvidersResponse,
+    GlobalModelCreate,
+    GlobalModelListResponse,
+    GlobalModelResponse,
+    GlobalModelUpdate,
+    GlobalModelWithStats,
+)
+from src.services.model.global_model import GlobalModelService
+
+router = APIRouter(prefix="/global", tags=["Admin - Global Models"])
+pipeline = ApiRequestPipeline()
+
+
+@router.get("", response_model=GlobalModelListResponse)
+async def list_global_models(
+    request: Request,
+    skip: int = Query(0, ge=0),
+    limit: int = Query(100, ge=1, le=1000),
+    is_active: Optional[bool] = Query(None),
+    search: Optional[str] = Query(None),
+    db: Session = Depends(get_db),
+) -> GlobalModelListResponse:
+    """获取 GlobalModel 列表"""
+    adapter = AdminListGlobalModelsAdapter(
+        skip=skip,
+        limit=limit,
+        is_active=is_active,
+        search=search,
+    )
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
+
+
+@router.get("/{global_model_id}", response_model=GlobalModelWithStats)
+async def get_global_model(
+    request: Request,
+    global_model_id: str,
+    db: Session = Depends(get_db),
+) -> GlobalModelWithStats:
+    """获取单个 GlobalModel 详情（含统计信息）"""
+    adapter = AdminGetGlobalModelAdapter(global_model_id=global_model_id)
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
+
+
+@router.post("", response_model=GlobalModelResponse, status_code=201)
+async def create_global_model(
+    request: Request,
+    payload: GlobalModelCreate,
+    db: Session = Depends(get_db),
+) -> GlobalModelResponse:
+    """创建 GlobalModel"""
+    adapter = AdminCreateGlobalModelAdapter(payload=payload)
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
+
+
+@router.patch("/{global_model_id}", response_model=GlobalModelResponse)
+async def update_global_model(
+    request: Request,
+    global_model_id: str,
+    payload: GlobalModelUpdate,
+    db: Session = Depends(get_db),
+) -> GlobalModelResponse:
+    """更新 GlobalModel"""
+    adapter = AdminUpdateGlobalModelAdapter(global_model_id=global_model_id, payload=payload)
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
+
+
+@router.delete("/{global_model_id}", status_code=204)
+async def delete_global_model(
+    request: Request,
+    global_model_id: str,
+    db: Session = Depends(get_db),
+):
+    """删除 GlobalModel（级联删除所有关联的 Provider 模型实现）"""
+    adapter = AdminDeleteGlobalModelAdapter(global_model_id=global_model_id)
+    await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
+    return None
+
+
+@router.post(
+    "/{global_model_id}/assign-to-providers", response_model=BatchAssignToProvidersResponse
+)
+async def batch_assign_to_providers(
+    request: Request,
+    global_model_id: str,
+    payload: BatchAssignToProvidersRequest,
+    db: Session = Depends(get_db),
+) -> BatchAssignToProvidersResponse:
+    """批量为多个 Provider 添加 GlobalModel 实现"""
+    adapter = AdminBatchAssignToProvidersAdapter(global_model_id=global_model_id, payload=payload)
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
+
+
+# ========== Adapters ==========
+
+
+@dataclass
+class AdminListGlobalModelsAdapter(AdminApiAdapter):
+    """列出 GlobalModel"""
+
+    skip: int
+    limit: int
+    is_active: Optional[bool]
+    search: Optional[str]
+
+    async def handle(self, context):  # type: ignore[override]
+        from sqlalchemy import func
+
+        from src.models.database import Model, ModelMapping
+
+        models = GlobalModelService.list_global_models(
+            db=context.db,
+            skip=self.skip,
+            limit=self.limit,
+            is_active=self.is_active,
+            search=self.search,
+        )
+
+        # 为每个 GlobalModel 添加统计数据
+        model_responses = []
+        for gm in models:
+            # 统计关联的 Model 数量（去重 Provider）
+            provider_count = (
+                context.db.query(func.count(func.distinct(Model.provider_id)))
+                .filter(Model.global_model_id == gm.id)
+                .scalar()
+                or 0
+            )
+
+            # 统计别名数量
+            alias_count = (
+                context.db.query(func.count(ModelMapping.id))
+                .filter(ModelMapping.target_global_model_id == gm.id)
+                .scalar()
+                or 0
+            )
+
+            response = GlobalModelResponse.model_validate(gm)
+            response.provider_count = provider_count
+            response.alias_count = alias_count
+            # usage_count 直接从 GlobalModel 表读取，已在 model_validate 中自动映射
+            model_responses.append(response)
+
+        return GlobalModelListResponse(
+            models=model_responses,
+            total=len(models),
+        )
+
+
+@dataclass
+class AdminGetGlobalModelAdapter(AdminApiAdapter):
+    """获取单个 GlobalModel"""
+
+    global_model_id: str
+
+    async def handle(self, context):  # type: ignore[override]
+        global_model = GlobalModelService.get_global_model(context.db, self.global_model_id)
+        stats = GlobalModelService.get_global_model_stats(context.db, self.global_model_id)
+
+        return GlobalModelWithStats(
+            **GlobalModelResponse.model_validate(global_model).model_dump(),
+            total_models=stats["total_models"],
+            total_providers=stats["total_providers"],
+            price_range=stats["price_range"],
+        )
+
+
+@dataclass
+class AdminCreateGlobalModelAdapter(AdminApiAdapter):
+    """创建 GlobalModel"""
+
+    payload: GlobalModelCreate
+
+    async def handle(self, context):  # type: ignore[override]
+        # 将 TieredPricingConfig 转换为 dict
+        tiered_pricing_dict = self.payload.default_tiered_pricing.model_dump()
+
+        global_model = GlobalModelService.create_global_model(
+            db=context.db,
+            name=self.payload.name,
+            display_name=self.payload.display_name,
+            description=self.payload.description,
+            official_url=self.payload.official_url,
+            icon_url=self.payload.icon_url,
+            is_active=self.payload.is_active,
+            # 按次计费配置
+            default_price_per_request=self.payload.default_price_per_request,
+            # 阶梯计费配置
+            default_tiered_pricing=tiered_pricing_dict,
+            # 默认能力配置
+            default_supports_vision=self.payload.default_supports_vision,
+            default_supports_function_calling=self.payload.default_supports_function_calling,
+            default_supports_streaming=self.payload.default_supports_streaming,
+            default_supports_extended_thinking=self.payload.default_supports_extended_thinking,
+            # Key 能力配置
+            supported_capabilities=self.payload.supported_capabilities,
+        )
+
+        logger.info(f"GlobalModel 已创建: id={global_model.id} name={global_model.name}")
+
+        return GlobalModelResponse.model_validate(global_model)
+
+
+@dataclass
+class AdminUpdateGlobalModelAdapter(AdminApiAdapter):
+    """更新 GlobalModel"""
+
+    global_model_id: str
+    payload: GlobalModelUpdate
+
+    async def handle(self, context):  # type: ignore[override]
+        global_model = GlobalModelService.update_global_model(
+            db=context.db,
+            global_model_id=self.global_model_id,
+            update_data=self.payload,
+        )
+
+        logger.info(f"GlobalModel 已更新: id={global_model.id} name={global_model.name}")
+
+        # 失效相关缓存
+        from src.services.cache.invalidation import get_cache_invalidation_service
+
+        cache_service = get_cache_invalidation_service()
+        cache_service.on_global_model_changed(global_model.name)
+
+        return GlobalModelResponse.model_validate(global_model)
+
+
+@dataclass
+class AdminDeleteGlobalModelAdapter(AdminApiAdapter):
+    """删除 GlobalModel（级联删除所有关联的 Provider 模型实现）"""
+
+    global_model_id: str
+
+    async def handle(self, context):  # type: ignore[override]
+        # 先获取 GlobalModel 信息（用于失效缓存）
+        from src.models.database import GlobalModel
+
+        global_model = (
+            context.db.query(GlobalModel).filter(GlobalModel.id == self.global_model_id).first()
+        )
+        model_name = global_model.name if global_model else None
+
+        GlobalModelService.delete_global_model(context.db, self.global_model_id)
+
+        logger.info(f"GlobalModel 已删除: id={self.global_model_id}")
+
+        # 失效相关缓存
+        if model_name:
+            from src.services.cache.invalidation import get_cache_invalidation_service
+
+            cache_service = get_cache_invalidation_service()
+            cache_service.on_global_model_changed(model_name)
+
+        return None
+
+
+@dataclass
+class AdminBatchAssignToProvidersAdapter(AdminApiAdapter):
+    """批量为 Provider 添加 GlobalModel 实现"""
+
+    global_model_id: str
+    payload: BatchAssignToProvidersRequest
+
+    async def handle(self, context):  # type: ignore[override]
+        result = GlobalModelService.batch_assign_to_providers(
+            db=context.db,
+            global_model_id=self.global_model_id,
+            provider_ids=self.payload.provider_ids,
+            create_models=self.payload.create_models,
+        )
+
+        logger.info(f"批量为 Provider 添加 GlobalModel: global_model_id={self.global_model_id} success={len(result['success'])} errors={len(result['errors'])}")
+
+        return BatchAssignToProvidersResponse(**result)

src/api/admin/models/mappings.py

@@ -0,0 +1,303 @@
+"""模型映射管理 API
+
+提供模型映射的 CRUD 操作。
+
+模型映射（Mapping）用于将源模型映射到目标模型，例如：
+- 请求 gpt-5.1 → Provider A 映射到 gpt-4
+- 用于处理 Provider 不支持请求模型的情况
+
+映射必须关联到特定的 Provider。
+"""
+
+import uuid
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy.orm import Session, joinedload
+
+from src.core.logger import logger
+from src.database import get_db
+from src.models.api import (
+    ModelMappingCreate,
+    ModelMappingResponse,
+    ModelMappingUpdate,
+)
+from src.models.database import GlobalModel, ModelMapping, Provider, User
+from src.services.cache.invalidation import get_cache_invalidation_service
+
+
+router = APIRouter(prefix="/mappings", tags=["Model Mappings"])
+
+
+def _serialize_mapping(mapping: ModelMapping) -> ModelMappingResponse:
+    target = mapping.target_global_model
+    provider = mapping.provider
+    scope = "provider" if mapping.provider_id else "global"
+    return ModelMappingResponse(
+        id=mapping.id,
+        source_model=mapping.source_model,
+        target_global_model_id=mapping.target_global_model_id,
+        target_global_model_name=target.name if target else None,
+        target_global_model_display_name=target.display_name if target else None,
+        provider_id=mapping.provider_id,
+        provider_name=provider.name if provider else None,
+        scope=scope,
+        mapping_type=mapping.mapping_type,
+        is_active=mapping.is_active,
+        created_at=mapping.created_at,
+        updated_at=mapping.updated_at,
+    )
+
+
+@router.get("", response_model=List[ModelMappingResponse])
+async def list_mappings(
+    provider_id: Optional[str] = Query(None, description="按 Provider 筛选"),
+    source_model: Optional[str] = Query(None, description="按源模型名筛选"),
+    target_global_model_id: Optional[str] = Query(None, description="按目标模型筛选"),
+    scope: Optional[str] = Query(None, description="global 或 provider"),
+    mapping_type: Optional[str] = Query(None, description="映射类型: alias 或 mapping"),
+    is_active: Optional[bool] = Query(None, description="按状态筛选"),
+    skip: int = Query(0, ge=0, description="跳过记录数"),
+    limit: int = Query(100, ge=1, le=1000, description="返回记录数"),
+    db: Session = Depends(get_db),
+):
+    """获取模型映射列表"""
+    query = db.query(ModelMapping).options(
+        joinedload(ModelMapping.target_global_model),
+        joinedload(ModelMapping.provider),
+    )
+
+    if provider_id is not None:
+        query = query.filter(ModelMapping.provider_id == provider_id)
+    if scope == "global":
+        query = query.filter(ModelMapping.provider_id.is_(None))
+    elif scope == "provider":
+        query = query.filter(ModelMapping.provider_id.isnot(None))
+    if mapping_type is not None:
+        query = query.filter(ModelMapping.mapping_type == mapping_type)
+    if source_model:
+        query = query.filter(ModelMapping.source_model.ilike(f"%{source_model}%"))
+    if target_global_model_id is not None:
+        query = query.filter(ModelMapping.target_global_model_id == target_global_model_id)
+    if is_active is not None:
+        query = query.filter(ModelMapping.is_active == is_active)
+
+    mappings = query.offset(skip).limit(limit).all()
+    return [_serialize_mapping(mapping) for mapping in mappings]
+
+
+@router.get("/{mapping_id}", response_model=ModelMappingResponse)
+async def get_mapping(
+    mapping_id: str,
+    db: Session = Depends(get_db),
+):
+    """获取单个模型映射"""
+    mapping = (
+        db.query(ModelMapping)
+        .options(
+            joinedload(ModelMapping.target_global_model),
+            joinedload(ModelMapping.provider),
+        )
+        .filter(ModelMapping.id == mapping_id)
+        .first()
+    )
+
+    if not mapping:
+        raise HTTPException(status_code=404, detail=f"映射 {mapping_id} 不存在")
+
+    return _serialize_mapping(mapping)
+
+
+@router.post("", response_model=ModelMappingResponse, status_code=201)
+async def create_mapping(
+    data: ModelMappingCreate,
+    db: Session = Depends(get_db),
+):
+    """创建模型映射"""
+    source_model = data.source_model.strip()
+    if not source_model:
+        raise HTTPException(status_code=400, detail="source_model 不能为空")
+
+    # 验证 mapping_type
+    if data.mapping_type not in ("alias", "mapping"):
+        raise HTTPException(status_code=400, detail="mapping_type 必须是 'alias' 或 'mapping'")
+
+    # 验证目标 GlobalModel 存在
+    target_model = (
+        db.query(GlobalModel)
+        .filter(GlobalModel.id == data.target_global_model_id, GlobalModel.is_active == True)
+        .first()
+    )
+    if not target_model:
+        raise HTTPException(
+            status_code=404, detail=f"目标模型 {data.target_global_model_id} 不存在或未激活"
+        )
+
+    # 验证 Provider 存在
+    provider = None
+    provider_id = data.provider_id
+    if provider_id:
+        provider = db.query(Provider).filter(Provider.id == provider_id).first()
+        if not provider:
+            raise HTTPException(status_code=404, detail=f"Provider {provider_id} 不存在")
+
+    # 检查映射是否已存在（全局或同一 Provider 下不可重复）
+    existing = (
+        db.query(ModelMapping)
+        .filter(
+            ModelMapping.source_model == source_model,
+            ModelMapping.provider_id == provider_id,
+        )
+        .first()
+    )
+    if existing:
+        raise HTTPException(status_code=400, detail="映射已存在")
+
+    # 创建映射
+    mapping = ModelMapping(
+        id=str(uuid.uuid4()),
+        source_model=source_model,
+        target_global_model_id=data.target_global_model_id,
+        provider_id=provider_id,
+        mapping_type=data.mapping_type,
+        is_active=data.is_active,
+        created_at=datetime.now(timezone.utc),
+        updated_at=datetime.now(timezone.utc),
+    )
+
+    db.add(mapping)
+    db.commit()
+    mapping = (
+        db.query(ModelMapping)
+        .options(
+            joinedload(ModelMapping.target_global_model),
+            joinedload(ModelMapping.provider),
+        )
+        .filter(ModelMapping.id == mapping.id)
+        .first()
+    )
+
+    logger.info(f"创建模型映射: {source_model} -> {target_model.name} "
+        f"(Provider: {provider.name if provider else 'global'}, ID: {mapping.id})")
+
+    cache_service = get_cache_invalidation_service()
+    cache_service.on_model_mapping_changed(source_model, provider_id)
+
+    return _serialize_mapping(mapping)
+
+
+@router.patch("/{mapping_id}", response_model=ModelMappingResponse)
+async def update_mapping(
+    mapping_id: str,
+    data: ModelMappingUpdate,
+    db: Session = Depends(get_db),
+):
+    """更新模型映射"""
+    mapping = db.query(ModelMapping).filter(ModelMapping.id == mapping_id).first()
+    if not mapping:
+        raise HTTPException(status_code=404, detail=f"映射 {mapping_id} 不存在")
+
+    update_data = data.model_dump(exclude_unset=True)
+
+    # 更新 Provider
+    if "provider_id" in update_data:
+        new_provider_id = update_data["provider_id"]
+        if new_provider_id:
+            provider = db.query(Provider).filter(Provider.id == new_provider_id).first()
+            if not provider:
+                raise HTTPException(status_code=404, detail=f"Provider {new_provider_id} 不存在")
+        mapping.provider_id = new_provider_id
+
+    # 更新目标模型
+    if "target_global_model_id" in update_data:
+        target_model = (
+            db.query(GlobalModel)
+            .filter(
+                GlobalModel.id == update_data["target_global_model_id"],
+                GlobalModel.is_active == True,
+            )
+            .first()
+        )
+        if not target_model:
+            raise HTTPException(
+                status_code=404,
+                detail=f"目标模型 {update_data['target_global_model_id']} 不存在或未激活",
+            )
+        mapping.target_global_model_id = update_data["target_global_model_id"]
+
+    # 更新源模型名
+    if "source_model" in update_data:
+        new_source = update_data["source_model"].strip()
+        if not new_source:
+            raise HTTPException(status_code=400, detail="source_model 不能为空")
+        mapping.source_model = new_source
+
+    # 检查唯一约束
+    duplicate = (
+        db.query(ModelMapping)
+        .filter(
+            ModelMapping.source_model == mapping.source_model,
+            ModelMapping.provider_id == mapping.provider_id,
+            ModelMapping.id != mapping_id,
+        )
+        .first()
+    )
+    if duplicate:
+        raise HTTPException(status_code=400, detail="映射已存在")
+
+    # 更新映射类型
+    if "mapping_type" in update_data:
+        if update_data["mapping_type"] not in ("alias", "mapping"):
+            raise HTTPException(status_code=400, detail="mapping_type 必须是 'alias' 或 'mapping'")
+        mapping.mapping_type = update_data["mapping_type"]
+
+    # 更新状态
+    if "is_active" in update_data:
+        mapping.is_active = update_data["is_active"]
+
+    mapping.updated_at = datetime.now(timezone.utc)
+    db.commit()
+    db.refresh(mapping)
+
+    logger.info(f"更新模型映射 (ID: {mapping.id})")
+
+    mapping = (
+        db.query(ModelMapping)
+        .options(
+            joinedload(ModelMapping.target_global_model),
+            joinedload(ModelMapping.provider),
+        )
+        .filter(ModelMapping.id == mapping.id)
+        .first()
+    )
+
+    cache_service = get_cache_invalidation_service()
+    cache_service.on_model_mapping_changed(mapping.source_model, mapping.provider_id)
+
+    return _serialize_mapping(mapping)
+
+
+@router.delete("/{mapping_id}", status_code=204)
+async def delete_mapping(
+    mapping_id: str,
+    db: Session = Depends(get_db),
+):
+    """删除模型映射"""
+    mapping = db.query(ModelMapping).filter(ModelMapping.id == mapping_id).first()
+
+    if not mapping:
+        raise HTTPException(status_code=404, detail=f"映射 {mapping_id} 不存在")
+
+    source_model = mapping.source_model
+    provider_id = mapping.provider_id
+
+    logger.info(f"删除模型映射: {source_model} -> {mapping.target_global_model_id} (ID: {mapping.id})")
+
+    db.delete(mapping)
+    db.commit()
+
+    cache_service = get_cache_invalidation_service()
+    cache_service.on_model_mapping_changed(source_model, provider_id)
+
+    return None