@kernel-sig/console 0.1.0

package/backend/app/services/ai_service.py

@@ -0,0 +1,569 @@
+"""AI 分析服务。
+
+职责边界：
+- 组装上下文（补丁正文、变更文件、提交信息）并套用领域 Prompt
+- 按任务路由选模型，调用 LLM 网关，解析结构化结果
+- 结果落库，并维护 ``input_hash`` 幂等
+
+**成本约束**：AI 调用是这套系统里唯一按次计费的部分，因此
+内容指纹未变时不重复调用；``force=True`` 才绕过该检查（人工重跑）。
+
+**失败不改状态**：分析失败只记录 error 与耗时，不抛给调用方 ——
+定时任务里一个 PR 的模型调用失败，不该让整轮分析中断。
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+
+import structlog
+from sqlalchemy import func, select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.config import Settings
+from app.core.exceptions import NotFoundError, ValidationError
+from app.integrations.llm import prompts
+from app.integrations.llm.provider import (
+    ChatMessage,
+    CompletionRequest,
+    LLMError,
+    OpenAICompatibleProvider,
+    extract_json,
+)
+from app.models.ai import (
+    AIAnalysis,
+    AITask,
+    AnalysisStatus,
+    LLMProvider,
+    TaskRouting,
+)
+from app.models.classification import SubjectType
+from app.models.issue import Issue
+from app.models.pull_request import PRCommit, PRFile, PullRequest
+from app.models.repository import Repository
+from app.services import classification_service, credential_service, sync_service
+
+logger = structlog.get_logger(__name__)
+
+# 单次送入模型的补丁上限。内核补丁动辄上万行，全量送入既超上下文
+# 也推高成本；截断处显式标注，避免模型误以为补丁就到这里。
+MAX_DIFF_CHARS = 60_000
+MAX_FILE_LIST = 200
+
+TRUNCATION_NOTE = "\n\n[补丁已截断，仅展示前 {shown} 行]"
+
+
+@dataclass
+class AnalysisTarget:
+    """一次分析的输入。input_hash 由此处的 variables 派生。"""
+
+    subject_type: SubjectType
+    subject_id: uuid.UUID
+    subject_number: int
+    subject_title: str
+    task: AITask
+    variables: dict[str, str] = field(default_factory=dict)
+
+    def input_hash(self) -> str:
+        # 与 sync_service.content_hash 用同一套指纹：任务类型与全部变量共同决定
+        return sync_service.content_hash(
+            self.task.value,
+            self.subject_title,
+            *[f"{key}={value}" for key, value in sorted(self.variables.items())],
+        )
+
+
+# ---------------------------------------------------------------------------
+# 模型选择
+# ---------------------------------------------------------------------------
+
+
+async def list_providers(session: AsyncSession) -> list[LLMProvider]:
+    stmt = select(LLMProvider).order_by(LLMProvider.is_default.desc(), LLMProvider.name)
+    return list((await session.scalars(stmt)).all())
+
+
+async def get_provider(session: AsyncSession, provider_id: uuid.UUID) -> LLMProvider | None:
+    return await session.get(LLMProvider, provider_id)
+
+
+async def require_provider(session: AsyncSession, provider_id: uuid.UUID) -> LLMProvider:
+    provider = await get_provider(session, provider_id)
+    if provider is None:
+        raise NotFoundError(
+            "模型提供方不存在", resource="llm_provider", identifier=str(provider_id)
+        )
+    return provider
+
+
+async def list_routing(session: AsyncSession) -> list[TaskRouting]:
+    return list((await session.scalars(select(TaskRouting).order_by(TaskRouting.task))).all())
+
+
+async def resolve_provider(
+    session: AsyncSession, task: AITask
+) -> tuple[LLMProvider, TaskRouting | None]:
+    """按任务解析出该用哪个模型。
+
+    路由缺失或指向的 provider 已停用时回落到 is_default 的 provider ——
+    宁可退回默认模型可用，也好过因为一条配置缺失让整条链路停摆；
+    但两者都没有配置时必须明确报错，而不是静默使用某个随机端点。
+    """
+    routing = await session.scalar(
+        select(TaskRouting).where(TaskRouting.task == task, TaskRouting.enabled.is_(True))
+    )
+    if routing is not None:
+        provider = await get_provider(session, routing.provider_id)
+        if provider is not None and provider.enabled:
+            return provider, routing
+        logger.warning(
+            "task_routing_provider_unavailable",
+            task=task.value,
+            provider_id=str(routing.provider_id),
+        )
+
+    provider = await session.scalar(
+        select(LLMProvider)
+        .where(LLMProvider.enabled.is_(True), LLMProvider.is_default.is_(True))
+        .limit(1)
+    )
+    if provider is None:
+        provider = await session.scalar(
+            select(LLMProvider).where(LLMProvider.enabled.is_(True)).limit(1)
+        )
+    if provider is None:
+        raise ValidationError("尚未配置可用的模型提供方，请先在「设置 → AI」中添加")
+    return provider, routing
+
+
+def build_client(settings: Settings, provider: LLMProvider, credential) -> OpenAICompatibleProvider:
+    api_key = credential_service.reveal(settings, credential) if credential else ""
+    return OpenAICompatibleProvider(
+        name=provider.name,
+        base_url=provider.base_url,
+        api_key=api_key,
+        default_model=provider.model,
+        timeout=float(provider.timeout_seconds),
+    )
+
+
+# ---------------------------------------------------------------------------
+# 上下文组装
+# ---------------------------------------------------------------------------
+
+
+def _truncate(text: str | None, limit: int = MAX_DIFF_CHARS) -> str:
+    text = text or ""
+    if len(text) <= limit:
+        return text
+    shown_lines = text[:limit].count("\n")
+    return text[:limit] + TRUNCATION_NOTE.format(shown=shown_lines)
+
+
+async def _pull_context(session: AsyncSession, pull: PullRequest, task: AITask) -> dict[str, str]:
+    """按任务组装 Prompt 变量。
+
+    不同任务需要的上下文差异很大：分类只看标题正文，风险审查需要完整补丁。
+    统一送全量上下文会让分类这种轻任务的成本与重任务持平。
+    """
+    commits = list(
+        (
+            await session.scalars(
+                select(PRCommit)
+                .where(PRCommit.pull_request_id == pull.id)
+                .order_by(PRCommit.sequence)
+            )
+        ).all()
+    )
+    files = list(
+        (
+            await session.scalars(
+                select(PRFile).where(PRFile.pull_request_id == pull.id).order_by(PRFile.filename)
+            )
+        ).all()
+    )
+
+    file_list = "\n".join(
+        f"{item.filename} (+{item.additions}/-{item.deletions})"
+        + (" [二进制]" if item.is_binary else "")
+        for item in files[:MAX_FILE_LIST]
+    )
+    commit_messages = "\n\n".join(
+        f"--- {commit.sha[:12]} ---\n{commit.message}" for commit in commits
+    )
+
+    variables = {
+        "title": pull.title,
+        "body": pull.body or "（无描述）",
+        "target_branch": pull.target_branch or "未知",
+        "author": pull.author_login or "未知",
+        "added_lines": str(pull.added_lines),
+        "removed_lines": str(pull.removed_lines),
+        "file_list": file_list or "（未同步变更文件）",
+        "commit_messages": commit_messages or "（未同步提交信息）",
+    }
+
+    if task in (AITask.RISK_REVIEW, AITask.BACKPORT_VERIFY):
+        parts = [
+            f"### {item.filename}\n{item.diff or '（补齐丁内容）'}"
+            for item in files
+            if not item.is_binary
+        ]
+        variables["diff"] = _truncate("\n\n".join(parts)) or "（未同步补丁内容）"
+        variables["backport_patch"] = variables["diff"]
+        variables["upstream_patch"] = _upstream_patch_hint(pull)
+
+    return variables
+
+
+def _upstream_patch_hint(pull: PullRequest) -> str:
+    """上游补丁原文不在本平台的数据范围内。
+
+    与其让模型凭空"想象"上游补丁再输出一份看似专业的对比结论，
+    不如如实告知缺失 —— 后者的结论至少是可判断的。
+    """
+    return (
+        "（未提供上游补丁原文。若无法核对，请在 summary 中说明并令 equivalent 为 null，"
+        "不要推测上游内容。）"
+    )
+
+
+async def build_target(
+    session: AsyncSession,
+    *,
+    task: AITask,
+    pull: PullRequest | None = None,
+    issue: Issue | None = None,
+) -> AnalysisTarget:
+    if pull is not None:
+        return AnalysisTarget(
+            subject_type=SubjectType.PULL_REQUEST,
+            subject_id=pull.id,
+            subject_number=pull.number,
+            subject_title=pull.title,
+            task=task,
+            variables=await _pull_context(session, pull, task),
+        )
+    if issue is not None:
+        return AnalysisTarget(
+            subject_type=SubjectType.ISSUE,
+            subject_id=issue.id,
+            subject_number=issue.number,
+            subject_title=issue.title,
+            task=task,
+            variables={
+                "title": issue.title,
+                "body": issue.body or "（无描述）",
+                "file_list": "（Issue 无变更文件）",
+            },
+        )
+    raise ValidationError("必须提供 PR 或 Issue 之一")
+
+
+# ---------------------------------------------------------------------------
+# 执行
+# ---------------------------------------------------------------------------
+
+
+async def get_analysis(
+    session: AsyncSession,
+    subject_type: SubjectType,
+    subject_id: uuid.UUID,
+    task: AITask,
+) -> AIAnalysis | None:
+    stmt = select(AIAnalysis).where(
+        AIAnalysis.subject_type == subject_type.value,
+        AIAnalysis.subject_id == subject_id,
+        AIAnalysis.task == task,
+    )
+    return await session.scalar(stmt)
+
+
+async def list_analyses(
+    session: AsyncSession,
+    subject_type: SubjectType,
+    subject_id: uuid.UUID,
+) -> list[AIAnalysis]:
+    stmt = (
+        select(AIAnalysis)
+        .where(
+            AIAnalysis.subject_type == subject_type.value,
+            AIAnalysis.subject_id == subject_id,
+        )
+        .order_by(AIAnalysis.created_at.desc())
+    )
+    return list((await session.scalars(stmt)).all())
+
+
+async def test_provider(session: AsyncSession, settings: Settings, provider: LLMProvider) -> dict:
+    """用一个最小请求验证端点、模型名与凭据是否真的可用。
+
+    只发一句 "ping"，不消耗有价值的 token，也不走 JSON 模式 ——
+    很多供应商的轻量模型不支持 response_format，用它测会把
+    "配置正确但选了不支持的模型"误报成连接失败。
+    """
+    credential = (
+        await credential_service.require_credential(session, provider.credential_id)
+        if provider.credential_id
+        else None
+    )
+    started = datetime.now(UTC)
+    try:
+        async with build_client(settings, provider, credential) as client:
+            response = await client.complete(
+                CompletionRequest(
+                    messages=[ChatMessage(role="user", content="ping")],
+                    model=provider.model,
+                    temperature=0.0,
+                    max_tokens=8,
+                    timeout=min(float(provider.timeout_seconds), 60.0),
+                )
+            )
+    except LLMError as exc:
+        provider.last_error = str(exc)[:500]
+        await session.flush()
+        return {"ok": False, "detail": str(exc), "latency_ms": None, "model": None}
+
+    latency_ms = int((datetime.now(UTC) - started).total_seconds() * 1000)
+    provider.last_used_at = datetime.now(UTC)
+    provider.last_error = None
+    await session.flush()
+    return {
+        "ok": True,
+        "detail": "端点可用",
+        "latency_ms": latency_ms,
+        "model": response.model,
+    }
+
+
+async def execute(
+    session: AsyncSession,
+    settings: Settings,
+    repository: Repository,
+    target: AnalysisTarget,
+    *,
+    triggered_by: uuid.UUID | None = None,
+    force: bool = False,
+) -> AIAnalysis:
+    """执行一次分析。幂等：输入未变且此前成功过则直接返回既有结果。"""
+    fingerprint = target.input_hash()
+    existing = await get_analysis(session, target.subject_type, target.subject_id, target.task)
+
+    if (
+        existing is not None
+        and not force
+        and existing.status is AnalysisStatus.SUCCEEDED
+        and existing.input_hash == fingerprint
+    ):
+        return existing
+
+    # 配置缺失属于部署问题，不是分析失败：在写任何状态之前就抛出去。
+    #
+    # 若把它当作分析失败落库，未配置模型时每轮定时任务都会写入几条 FAILED ——
+    # 用量面板上看起来像模型出了故障，实际只是还没配；而且这些空记录
+    # 会一直累积下去。这里提前解析，让调用方能拿到"尚未配置"这个明确信号。
+    provider, routing = await resolve_provider(session, target.task)
+    credential = (
+        await credential_service.require_credential(session, provider.credential_id)
+        if provider.credential_id
+        else None
+    )
+
+    if existing is None:
+        fresh = AIAnalysis(
+            repository_id=repository.id,
+            subject_type=target.subject_type.value,
+            subject_id=target.subject_id,
+            task=target.task,
+        )
+        try:
+            # 唯一约束 (subject_type, subject_id, task) 规定一个对象只有一行，
+            # 但"先查再插"挡不住并发：定时任务和用户点「重新分析」可能同时
+            # 选中同一个对象，两边的 SELECT 都看不见对方还没提交的行，于是
+            # 都走到这里插入。后到的那次会被唯一约束拦下 —— 接住它，改用
+            # 对方那条记录继续写即可。不接的话，IntegrityError 会一路冒到
+            # 接口层变成 500，而它本来只是"别人已经在分析了"。
+            #
+            # add 必须写在 SAVEPOINT 之内：写在外面时 flush 失败会把**整个
+            # 会话**标记成待回滚（PendingRollbackError），而 worker 一个会话
+            # 要连着分析几十个对象，作废一次等于整批白跑。两种写法都实测过。
+            async with session.begin_nested():
+                session.add(fresh)
+                await session.flush()
+            existing = fresh
+        except IntegrityError:
+            existing = await get_analysis(
+                session, target.subject_type, target.subject_id, target.task
+            )
+            if existing is None:
+                raise
+
+    existing.status = AnalysisStatus.RUNNING
+    existing.input_hash = fingerprint
+    existing.started_at = datetime.now(UTC)
+    existing.finished_at = None
+    existing.error = None
+    existing.triggered_by = triggered_by
+    await session.flush()
+
+    try:
+        system_prompt, user_template = _template_for(target.task, routing)
+        messages = [
+            ChatMessage(role="system", content=system_prompt),
+            ChatMessage(role="user", content=_render(user_template, target.variables)),
+        ]
+
+        async with build_client(settings, provider, credential) as client:
+            response = await client.complete(
+                CompletionRequest(
+                    messages=messages,
+                    model=provider.model,
+                    temperature=provider.temperature,
+                    max_tokens=provider.max_tokens,
+                    json_mode=target.task is not AITask.RISK_REVIEW,
+                    timeout=float(provider.timeout_seconds),
+                )
+            )
+
+        existing.result = extract_json(response.content)
+        existing.raw_response = response.content
+        existing.model = response.model
+        existing.provider_name = provider.name
+        existing.prompt_tokens = response.prompt_tokens
+        existing.completion_tokens = response.completion_tokens
+        existing.status = AnalysisStatus.SUCCEEDED
+
+        provider.last_used_at = datetime.now(UTC)
+        provider.last_error = None
+    except LLMError as exc:
+        # 上游/模型侧失败只落状态，不往上抛：定时任务里单条失败不该中断整轮
+        existing.status = AnalysisStatus.FAILED
+        existing.error = str(exc)[:2000]
+        logger.warning(
+            "ai_analysis_failed",
+            task=target.task.value,
+            subject=target.subject_number,
+            error=str(exc),
+        )
+        provider.last_error = str(exc)[:500]
+    finally:
+        existing.finished_at = datetime.now(UTC)
+        await session.flush()
+
+    return existing
+
+
+def _template_for(task: AITask, routing: TaskRouting | None) -> tuple[str, str]:
+    """取 Prompt 模板。路由上配置的 system_prompt 覆盖内置版本。"""
+    system_prompt, user_template = prompts.get_template(task.value)
+    if routing is not None and routing.system_prompt:
+        system_prompt = routing.system_prompt
+    return system_prompt, user_template
+
+
+def _render(template: str, variables: dict[str, str]) -> str:
+    """填充模板占位符。
+
+    用 ``format_map`` 配合缺失键兜底类，而不是 ``str.format``：
+    模型的输出模板由用户可编辑，某个占位符写错不该让整次分析崩掉。
+    """
+
+    class _Safe(dict):
+        def __missing__(self, key: str) -> str:
+            return f"（缺少 {key}）"
+
+    return template.format_map(_Safe(variables))
+
+
+# ---------------------------------------------------------------------------
+# 与分类子系统的衔接
+# ---------------------------------------------------------------------------
+
+
+async def classify_subject(
+    session: AsyncSession,
+    settings: Settings,
+    repository: Repository,
+    *,
+    pull: PullRequest | None = None,
+    issue: Issue | None = None,
+    triggered_by: uuid.UUID | None = None,
+    force: bool = False,
+) -> AIAnalysis:
+    """用模型补判规则未命中的分类，并把结果写回分类表。"""
+    target = await build_target(session, task=AITask.CLASSIFY, pull=pull, issue=issue)
+    analysis = await execute(
+        session, settings, repository, target, triggered_by=triggered_by, force=force
+    )
+
+    if analysis.status is AnalysisStatus.SUCCEEDED and analysis.result:
+        result = analysis.result
+        await classification_service.apply_ai_result(
+            session,
+            repository_id=repository.id,
+            subject_type=target.subject_type,
+            subject_id=target.subject_id,
+            kind=str(result.get("kind", "unknown")),
+            subsystem=result.get("subsystem"),
+            confidence=float(result.get("confidence") or 0.0),
+            reason=result.get("reason"),
+        )
+    return analysis
+
+
+# ---------------------------------------------------------------------------
+# 用量
+# ---------------------------------------------------------------------------
+
+
+async def usage_stats(
+    session: AsyncSession,
+    *,
+    repository_id: uuid.UUID | None = None,
+    since_days: int = 30,
+) -> dict:
+    """统计模型用量。
+
+    AI 调用是这套系统里唯一按次计费的开销，用量必须能被直接看到 ——
+    否则"这个月为什么花了这么多"永远查不清。
+    """
+    cutoff = datetime.now(UTC) - timedelta(days=since_days)
+    conditions = [AIAnalysis.created_at >= cutoff]
+    if repository_id is not None:
+        conditions.append(AIAnalysis.repository_id == repository_id)
+
+    stmt = (
+        select(
+            AIAnalysis.task,
+            AIAnalysis.status,
+            func.count(),
+            func.coalesce(func.sum(AIAnalysis.prompt_tokens), 0),
+            func.coalesce(func.sum(AIAnalysis.completion_tokens), 0),
+        )
+        .where(*conditions)
+        .group_by(AIAnalysis.task, AIAnalysis.status)
+    )
+
+    analyses = succeeded = failed = prompt_tokens = completion_tokens = 0
+    by_task: dict[str, int] = {}
+    for task, status, count, prompt, completion in (await session.execute(stmt)).all():
+        analyses += count
+        prompt_tokens += prompt
+        completion_tokens += completion
+        by_task[task.value] = by_task.get(task.value, 0) + count
+        if status is AnalysisStatus.SUCCEEDED:
+            succeeded += count
+        elif status is AnalysisStatus.FAILED:
+            failed += count
+
+    return {
+        "analyses": analyses,
+        "succeeded": succeeded,
+        "failed": failed,
+        "prompt_tokens": prompt_tokens,
+        "completion_tokens": completion_tokens,
+        "by_task": by_task,
+    }