350 lines
13 KiB
Python
350 lines
13 KiB
Python
"""
|
||
Retrieval Strategy API Endpoints.
|
||
[AC-AISVC-RES-01~15] 策略管理 API。
|
||
|
||
Endpoints:
|
||
- GET /strategy/retrieval/current - 获取当前策略状态
|
||
- POST /strategy/retrieval/switch - 切换策略
|
||
- POST /strategy/retrieval/validate - 验证策略配置
|
||
- POST /strategy/retrieval/rollback - 回退策略
|
||
"""
|
||
|
||
import logging
|
||
from typing import Any
|
||
|
||
from fastapi import APIRouter, HTTPException, status
|
||
from pydantic import BaseModel, Field
|
||
|
||
from app.services.retrieval.strategy.config import (
|
||
GrayscaleConfig,
|
||
ModeRouterConfig,
|
||
PipelineConfig,
|
||
RetrievalStrategyConfig,
|
||
RerankerConfig,
|
||
RuntimeMode,
|
||
StrategyType,
|
||
)
|
||
from app.services.retrieval.strategy.rollback_manager import (
|
||
RollbackManager,
|
||
RollbackResult,
|
||
RollbackTrigger,
|
||
get_rollback_manager,
|
||
)
|
||
from app.services.retrieval.strategy.strategy_router import (
|
||
StrategyRouter,
|
||
get_strategy_router,
|
||
set_strategy_router,
|
||
)
|
||
|
||
logger = logging.getLogger(__name__)
|
||
|
||
router = APIRouter(prefix="/strategy/retrieval", tags=["strategy"])
|
||
|
||
|
||
class GrayscaleConfigSchema(BaseModel):
|
||
"""灰度配置 Schema。"""
|
||
enabled: bool = False
|
||
percentage: float = Field(default=0.0, ge=0.0, le=100.0)
|
||
allowlist: list[str] = Field(default_factory=list)
|
||
|
||
|
||
class RerankerConfigSchema(BaseModel):
|
||
"""重排器配置 Schema。"""
|
||
enabled: bool = False
|
||
model: str = "cross-encoder"
|
||
top_k_after_rerank: int = 5
|
||
min_score_threshold: float = 0.3
|
||
|
||
|
||
class ModeRouterConfigSchema(BaseModel):
|
||
"""模式路由配置 Schema。"""
|
||
runtime_mode: str = "direct"
|
||
react_trigger_confidence_threshold: float = 0.6
|
||
react_trigger_complexity_score: float = 0.5
|
||
react_max_steps: int = 5
|
||
direct_fallback_on_low_confidence: bool = True
|
||
|
||
|
||
class PipelineConfigSchema(BaseModel):
|
||
"""Pipeline 配置 Schema。"""
|
||
top_k: int = 5
|
||
score_threshold: float = 0.01
|
||
min_hits: int = 1
|
||
two_stage_enabled: bool = True
|
||
|
||
|
||
class StrategyStatusResponse(BaseModel):
|
||
"""策略状态响应。"""
|
||
active_strategy: str
|
||
grayscale: GrayscaleConfigSchema
|
||
pipeline: PipelineConfigSchema
|
||
reranker: RerankerConfigSchema
|
||
mode_router: ModeRouterConfigSchema
|
||
performance_thresholds: dict[str, float] = Field(default_factory=dict)
|
||
|
||
|
||
class SwitchRequest(BaseModel):
|
||
"""策略切换请求。"""
|
||
active_strategy: str | None = None
|
||
grayscale: GrayscaleConfigSchema | None = None
|
||
mode_router: ModeRouterConfigSchema | None = None
|
||
reranker: RerankerConfigSchema | None = None
|
||
|
||
|
||
class SwitchResponse(BaseModel):
|
||
"""策略切换响应。"""
|
||
success: bool
|
||
previous_strategy: str
|
||
current_strategy: str
|
||
message: str
|
||
|
||
|
||
class ValidationRequest(BaseModel):
|
||
"""策略验证请求。"""
|
||
config: dict[str, Any] = Field(default_factory=dict)
|
||
|
||
|
||
class ValidationResponse(BaseModel):
|
||
"""策略验证响应。"""
|
||
valid: bool
|
||
errors: list[str] = Field(default_factory=list)
|
||
warnings: list[str] = Field(default_factory=list)
|
||
config_summary: dict[str, Any] = Field(default_factory=dict)
|
||
|
||
|
||
class RollbackResponse(BaseModel):
|
||
"""策略回退响应。"""
|
||
success: bool
|
||
previous_strategy: str
|
||
current_strategy: str
|
||
trigger: str
|
||
reason: str
|
||
audit_log_id: str | None = None
|
||
|
||
|
||
@router.get(
|
||
"/current",
|
||
response_model=StrategyStatusResponse,
|
||
summary="获取当前策略状态",
|
||
description="【AC-AISVC-RES-01】 获取当前活跃的检索策略配置状态。",
|
||
)
|
||
async def get_current_strategy() -> StrategyStatusResponse:
|
||
"""
|
||
【AC-AISVC-RES-01】 获取当前策略状态。
|
||
"""
|
||
strategy_router = get_strategy_router()
|
||
config = strategy_router.get_config()
|
||
|
||
return StrategyStatusResponse(
|
||
active_strategy=config.active_strategy.value,
|
||
grayscale=GrayscaleConfigSchema(
|
||
enabled=config.grayscale.enabled,
|
||
percentage=config.grayscale.percentage,
|
||
allowlist=config.grayscale.allowlist,
|
||
),
|
||
pipeline=PipelineConfigSchema(
|
||
top_k=config.pipeline.top_k,
|
||
score_threshold=config.pipeline.score_threshold,
|
||
min_hits=config.pipeline.min_hits,
|
||
two_stage_enabled=config.pipeline.two_stage_enabled,
|
||
),
|
||
reranker=RerankerConfigSchema(
|
||
enabled=config.reranker.enabled,
|
||
model=config.reranker.model,
|
||
top_k_after_rerank=config.reranker.top_k_after_rerank,
|
||
min_score_threshold=config.reranker.min_score_threshold,
|
||
),
|
||
mode_router=ModeRouterConfigSchema(
|
||
runtime_mode=config.mode_router.runtime_mode.value,
|
||
react_trigger_confidence_threshold=config.mode_router.react_trigger_confidence_threshold,
|
||
react_trigger_complexity_score=config.mode_router.react_trigger_complexity_score,
|
||
react_max_steps=config.mode_router.react_max_steps,
|
||
direct_fallback_on_low_confidence=config.mode_router.direct_fallback_on_low_confidence,
|
||
),
|
||
performance_thresholds=config.performance_thresholds,
|
||
)
|
||
|
||
|
||
@router.post(
|
||
"/switch",
|
||
response_model=SwitchResponse,
|
||
summary="切换策略",
|
||
description="【AC-AISVC-RES-02, AC-AISVC-RES-03】 切换检索策略， 支持灰度发布配置。",
|
||
)
|
||
async def switch_strategy(request: SwitchRequest) -> SwitchResponse:
|
||
"""
|
||
【AC-AISVC-RES-02, AC-AISVC-RES-03】 切换策略。
|
||
|
||
支持灰度发布配置（percentage/allowlist）。
|
||
"""
|
||
strategy_router = get_strategy_router()
|
||
current_config = strategy_router.get_config()
|
||
previous_strategy = current_config.active_strategy.value
|
||
|
||
try:
|
||
new_active_strategy = StrategyType(request.active_strategy) if request.active_strategy else current_config.active_strategy
|
||
except ValueError as e:
|
||
raise HTTPException(
|
||
status_code=400,
|
||
detail=f"Invalid strategy type: {request.active_strategy}. Valid values are: default, enhanced",
|
||
)
|
||
|
||
new_config = RetrievalStrategyConfig(
|
||
active_strategy=new_active_strategy,
|
||
grayscale=GrayscaleConfig(
|
||
enabled=request.grayscale.enabled if request.grayscale else current_config.grayscale.enabled,
|
||
percentage=request.grayscale.percentage if request.grayscale else current_config.grayscale.percentage,
|
||
allowlist=request.grayscale.allowlist if request.grayscale else current_config.grayscale.allowlist,
|
||
),
|
||
mode_router=ModeRouterConfig(
|
||
runtime_mode=RuntimeMode(request.mode_router.runtime_mode) if request.mode_router and request.mode_router.runtime_mode else current_config.mode_router.runtime_mode,
|
||
react_trigger_confidence_threshold=request.mode_router.react_trigger_confidence_threshold if request.mode_router else current_config.mode_router.react_trigger_confidence_threshold,
|
||
react_trigger_complexity_score=request.mode_router.react_trigger_complexity_score if request.mode_router else current_config.mode_router.react_trigger_complexity_score,
|
||
react_max_steps=request.mode_router.react_max_steps if request.mode_router else current_config.mode_router.react_max_steps,
|
||
direct_fallback_on_low_confidence=request.mode_router.direct_fallback_on_low_confidence if request.mode_router else current_config.mode_router.direct_fallback_on_low_confidence,
|
||
) if request.mode_router else current_config.mode_router,
|
||
reranker=RerankerConfig(
|
||
enabled=request.reranker.enabled if request.reranker else current_config.reranker.enabled,
|
||
model=request.reranker.model if request.reranker else current_config.reranker.model,
|
||
top_k_after_rerank=request.reranker.top_k_after_rerank if request.reranker else current_config.reranker.top_k_after_rerank,
|
||
min_score_threshold=request.reranker.min_score_threshold if request.reranker else current_config.reranker.min_score_threshold,
|
||
) if request.reranker else current_config.reranker,
|
||
pipeline=current_config.pipeline,
|
||
metadata_inference=current_config.metadata_inference,
|
||
performance_thresholds=current_config.performance_thresholds,
|
||
)
|
||
|
||
strategy_router.update_config(new_config)
|
||
|
||
logger.info(
|
||
f"[AC-AISVC-RES-02] Strategy switched: {previous_strategy} -> {new_config.active_strategy.value}"
|
||
)
|
||
|
||
return SwitchResponse(
|
||
success=True,
|
||
previous_strategy=previous_strategy,
|
||
current_strategy=new_config.active_strategy.value,
|
||
message=f"Strategy switched from {previous_strategy} to {new_config.active_strategy.value}",
|
||
)
|
||
|
||
|
||
@router.post(
|
||
"/validate",
|
||
response_model=ValidationResponse,
|
||
summary="验证策略配置",
|
||
description="【AC-AISVC-RES-06, AC-AISVC-RES-08】 验证策略配置的完整性与一致性。",
|
||
)
|
||
async def validate_strategy(request: ValidationRequest) -> ValidationResponse:
|
||
"""
|
||
【AC-AISVC-RES-06, AC-AISVC-RES-08】 验证策略配置。
|
||
"""
|
||
errors: list[str] = []
|
||
warnings: list[str] = []
|
||
config = request.config
|
||
|
||
if "active_strategy" in config:
|
||
if config["active_strategy"] not in ["default", "enhanced"]:
|
||
errors.append(f"Invalid active_strategy: {config['active_strategy']}")
|
||
|
||
if "grayscale" in config:
|
||
grayscale = config["grayscale"]
|
||
if grayscale.get("percentage", 1.0) is not None:
|
||
if not (0 <= grayscale["percentage"] <= 100):
|
||
errors.append(f"Invalid grayscale percentage: {grayscale['percentage']}")
|
||
|
||
if "mode_router" in config:
|
||
mode_router = config["mode_router"]
|
||
if "runtime_mode" in mode_router:
|
||
if mode_router["runtime_mode"] not in ["direct", "react", "auto"]:
|
||
errors.append(f"Invalid runtime_mode: {mode_router['runtime_mode']}")
|
||
|
||
if "reranker" in config:
|
||
reranker = config["reranker"]
|
||
if reranker.get("enabled") and reranker.get("top_k_after_rerank", 1) > 20:
|
||
warnings.append(f"top_k_after_rerank should be between 1 and 20, current: {reranker['top_k_after_rerank']}")
|
||
|
||
if "performance_thresholds" in config:
|
||
thresholds = config["performance_thresholds"]
|
||
if thresholds.get("max_latency_ms", 0) is not None and thresholds["max_latency_ms"] < 100:
|
||
warnings.append(f"max_latency_ms seems too low: {thresholds['max_latency_ms']}ms")
|
||
|
||
return ValidationResponse(
|
||
valid=len(errors) == 0,
|
||
errors=errors,
|
||
warnings=warnings,
|
||
config_summary={
|
||
"active_strategy": config.get("active_strategy", "default"),
|
||
"grayscale_enabled": config.get("grayscale", {}).get("enabled", False),
|
||
"runtime_mode": config.get("mode_router", {}).get("runtime_mode", "direct"),
|
||
"reranker_enabled": config.get("reranker", {}).get("enabled", False),
|
||
"performance_thresholds": config.get("performance_thresholds", {}),
|
||
},
|
||
)
|
||
|
||
|
||
@router.post(
|
||
"/rollback",
|
||
response_model=RollbackResponse,
|
||
summary="回退策略",
|
||
description="【AC-AISVC-RES-07】 回退到默认策略。",
|
||
)
|
||
async def rollback_strategy(
|
||
trigger: str = "manual",
|
||
reason: str = "",
|
||
) -> RollbackResponse:
|
||
"""
|
||
【AC-AISVC-RES-07】 回退策略。
|
||
|
||
支持手动触发和自动触发（性能退化、异常）。
|
||
"""
|
||
strategy_router = get_strategy_router()
|
||
current_config = strategy_router.get_config()
|
||
previous_strategy = current_config.active_strategy
|
||
|
||
if previous_strategy == StrategyType.DEFAULT:
|
||
return RollbackResponse(
|
||
success=False,
|
||
previous_strategy=previous_strategy.value,
|
||
current_strategy=previous_strategy.value,
|
||
trigger=trigger,
|
||
reason="Already on default strategy",
|
||
audit_log_id=None,
|
||
)
|
||
|
||
new_config = RetrievalStrategyConfig(
|
||
active_strategy=StrategyType.DEFAULT,
|
||
grayscale=current_config.grayscale,
|
||
mode_router=current_config.mode_router,
|
||
reranker=current_config.reranker,
|
||
pipeline=current_config.pipeline,
|
||
metadata_inference=current_config.metadata_inference,
|
||
performance_thresholds=current_config.performance_thresholds,
|
||
)
|
||
strategy_router.update_config(new_config)
|
||
|
||
rollback_manager = get_rollback_manager()
|
||
rollback_manager.update_config(new_config)
|
||
|
||
audit_log = rollback_manager.record_audit(
|
||
action="rollback",
|
||
details={
|
||
"from_strategy": previous_strategy.value,
|
||
"to_strategy": StrategyType.DEFAULT.value,
|
||
"trigger": trigger,
|
||
"reason": reason or "Manual rollback",
|
||
},
|
||
)
|
||
|
||
logger.info(
|
||
f"[AC-AISVC-RES-07] Strategy rolled back: {previous_strategy.value} -> default"
|
||
)
|
||
|
||
return RollbackResponse(
|
||
success=True,
|
||
previous_strategy=previous_strategy.value,
|
||
current_strategy=StrategyType.DEFAULT.value,
|
||
trigger=trigger,
|
||
reason=reason or "Manual rollback",
|
||
audit_log_id=str(audit_log.timestamp) if audit_log else None,
|
||
)
|