提交 99090008 authored 作者: caifuming's avatar caifuming

ljy_统一 LLM 调用,支持多模型切换、异常降级

上级 cc32bf75
"""Internal authentication helpers for AI endpoints."""
from __future__ import annotations
import os
import secrets
from fastapi import HTTPException, Request, status
def _get_expected_internal_token() -> str:
return os.getenv("AI_INTERNAL_TOKEN", "dev-internal-token")
def require_internal_token(
request: Request,
) -> None:
expected_token = _get_expected_internal_token()
x_internal_token = request.headers.get("X-Internal-Token")
if not x_internal_token or not secrets.compare_digest(x_internal_token, expected_token):
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Invalid internal token.",
)
...@@ -20,3 +20,7 @@ class AIServiceHealthTracker: ...@@ -20,3 +20,7 @@ class AIServiceHealthTracker:
@property @property
def consecutive_failures(self) -> int: def consecutive_failures(self) -> int:
return self._consecutive_failures return self._consecutive_failures
@property
def failure_threshold(self) -> int:
return self._failure_threshold
...@@ -43,3 +43,14 @@ class AIChatResponse(BaseModel): ...@@ -43,3 +43,14 @@ class AIChatResponse(BaseModel):
prompt_name: str | None = None prompt_name: str | None = None
prompt_version: str | None = None prompt_version: str | None = None
error: AIResponseError | None = None error: AIResponseError | None = None
class AIHealthResponse(BaseModel):
status: Literal["ok", "unhealthy"]
service: str
unhealthy: bool
consecutive_failures: int
failure_threshold: int
default_provider: str
default_model: str
rate_limit_rps: int
...@@ -6,21 +6,28 @@ import os ...@@ -6,21 +6,28 @@ import os
import time import time
from dataclasses import dataclass from dataclasses import dataclass
from functools import lru_cache from functools import lru_cache
import json
from uuid import uuid4 from uuid import uuid4
from app.ai_calling.call_log import CallLogger from app.ai_calling.call_log import CallLogger
from app.ai_calling.errors import ( from app.ai_calling.errors import (
ALL_PROVIDERS_FAILED, ALL_PROVIDERS_FAILED,
MODEL_NOT_CONFIGURED, MODEL_NOT_CONFIGURED,
MODEL_TIMEOUT,
AIServiceError, AIServiceError,
) )
from app.ai_calling.fallback import build_error_response, build_fallback_response from app.ai_calling.fallback import build_error_response, build_fallback_response
from app.ai_calling.health import AIServiceHealthTracker from app.ai_calling.health import AIServiceHealthTracker
from app.ai_calling.limiter import InMemoryRateLimiter from app.ai_calling.limiter import InMemoryRateLimiter
from app.ai_calling.schemas import AIChatRequest, AIChatResponse, AIResponseData from app.ai_calling.schemas import (
AIChatRequest,
AIChatResponse,
AIHealthResponse,
AIResponseData,
)
from app.llm.base import ProviderRequest, ProviderResult from app.llm.base import ProviderRequest, ProviderResult
from app.llm.factory import ProviderFactory, ProviderFactoryConfig from app.llm.factory import ProviderFactory, ProviderFactoryConfig
from app.prompt.loader import PromptLoader, PromptTemplate from app.prompt.loader import PromptLoader
@dataclass(frozen=True, slots=True) @dataclass(frozen=True, slots=True)
...@@ -36,6 +43,10 @@ class AISettings: ...@@ -36,6 +43,10 @@ class AISettings:
openai_api_key: str | None openai_api_key: str | None
openai_base_url: str openai_base_url: str
openai_organization: str | None openai_organization: str | None
tongyi_api_key: str | None
tongyi_base_url: str | None
wenxin_api_key: str | None
wenxin_base_url: str | None
@classmethod @classmethod
def from_env(cls) -> "AISettings": def from_env(cls) -> "AISettings":
...@@ -52,6 +63,10 @@ class AISettings: ...@@ -52,6 +63,10 @@ class AISettings:
openai_api_key=os.getenv("OPENAI_API_KEY"), openai_api_key=os.getenv("OPENAI_API_KEY"),
openai_base_url=os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1"), openai_base_url=os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1"),
openai_organization=os.getenv("OPENAI_ORGANIZATION"), openai_organization=os.getenv("OPENAI_ORGANIZATION"),
tongyi_api_key=os.getenv("TONGYI_API_KEY"),
tongyi_base_url=os.getenv("TONGYI_BASE_URL"),
wenxin_api_key=os.getenv("WENXIN_API_KEY"),
wenxin_base_url=os.getenv("WENXIN_BASE_URL"),
) )
...@@ -120,6 +135,11 @@ class AICallingService: ...@@ -120,6 +135,11 @@ class AICallingService:
request=request, request=request,
trace_id=trace_id, trace_id=trace_id,
) )
result = self._normalize_provider_result(
prompt=prompt,
request=request,
result=result,
)
except AIServiceError as exc: except AIServiceError as exc:
last_error = exc last_error = exc
self._call_logger.log( self._call_logger.log(
...@@ -214,7 +234,7 @@ class AICallingService: ...@@ -214,7 +234,7 @@ class AICallingService:
) )
except asyncio.TimeoutError as exc: except asyncio.TimeoutError as exc:
last_error = AIServiceError( last_error = AIServiceError(
"MODEL_TIMEOUT", MODEL_TIMEOUT,
"Model request timed out.", "Model request timed out.",
retryable=current_attempt < attempts - 1, retryable=current_attempt < attempts - 1,
) )
...@@ -231,6 +251,41 @@ class AICallingService: ...@@ -231,6 +251,41 @@ class AICallingService:
"All configured providers failed.", "All configured providers failed.",
) )
def get_health_status(self) -> AIHealthResponse:
unhealthy = self._health_tracker.unhealthy
return AIHealthResponse(
status="unhealthy" if unhealthy else "ok",
service="ai-service",
unhealthy=unhealthy,
consecutive_failures=self._health_tracker.consecutive_failures,
failure_threshold=self._health_tracker.failure_threshold,
default_provider=self._settings.default_provider,
default_model=self._settings.default_model,
rate_limit_rps=self._settings.rate_limit_rps,
)
def _normalize_provider_result(
self,
*,
prompt,
request: AIChatRequest,
result: ProviderResult,
) -> ProviderResult:
if request.response_format != "json":
return result
structured = self._prompt_loader.normalize_structured_output(
prompt,
result.content,
result.structured,
)
content = result.content or json.dumps(structured, ensure_ascii=True)
return ProviderResult(
content=content,
structured=structured,
raw=result.raw,
)
def _build_provider_targets(self, request: AIChatRequest) -> list[tuple[str, str]]: def _build_provider_targets(self, request: AIChatRequest) -> list[tuple[str, str]]:
primary_provider = (request.provider or self._settings.default_provider or "").strip() primary_provider = (request.provider or self._settings.default_provider or "").strip()
primary_model = (request.model or self._settings.default_model or "").strip() primary_model = (request.model or self._settings.default_model or "").strip()
...@@ -266,6 +321,10 @@ def get_ai_service() -> AICallingService: ...@@ -266,6 +321,10 @@ def get_ai_service() -> AICallingService:
openai_api_key=settings.openai_api_key, openai_api_key=settings.openai_api_key,
openai_base_url=settings.openai_base_url, openai_base_url=settings.openai_base_url,
openai_organization=settings.openai_organization, openai_organization=settings.openai_organization,
tongyi_api_key=settings.tongyi_api_key,
tongyi_base_url=settings.tongyi_base_url,
wenxin_api_key=settings.wenxin_api_key,
wenxin_base_url=settings.wenxin_base_url,
) )
) )
return AICallingService( return AICallingService(
......
"""AI chat API routes.""" """AI chat API routes."""
from fastapi import APIRouter from fastapi import APIRouter, Depends
from app.ai_calling.schemas import AIChatRequest, AIChatResponse from app.ai_calling.auth import require_internal_token
from app.ai_calling.schemas import AIChatRequest, AIChatResponse, AIHealthResponse
from app.ai_calling.service import get_ai_service from app.ai_calling.service import get_ai_service
router = APIRouter() router = APIRouter()
@router.post("/chat", response_model=AIChatResponse) @router.post("/chat", response_model=AIChatResponse, dependencies=[Depends(require_internal_token)])
async def chat(req: AIChatRequest) -> AIChatResponse: async def chat(req: AIChatRequest) -> AIChatResponse:
"""Unified LLM chat entrypoint.""" """Unified LLM chat entrypoint."""
service = get_ai_service() service = get_ai_service()
return await service.chat(req) return await service.chat(req)
@router.get("/health", response_model=AIHealthResponse, dependencies=[Depends(require_internal_token)])
async def ai_health() -> AIHealthResponse:
"""Return AI-calling specific health status without changing legacy health output."""
service = get_ai_service()
return service.get_health_status()
...@@ -7,6 +7,8 @@ from app.ai_calling.errors import MODEL_NOT_CONFIGURED, AIServiceError ...@@ -7,6 +7,8 @@ from app.ai_calling.errors import MODEL_NOT_CONFIGURED, AIServiceError
from app.llm.base import LLMProvider from app.llm.base import LLMProvider
from app.llm.mock import MockProvider from app.llm.mock import MockProvider
from app.llm.openai import OpenAIProvider from app.llm.openai import OpenAIProvider
from app.llm.tongyi import TongyiProvider
from app.llm.wenxin import WenxinProvider
@dataclass(frozen=True, slots=True) @dataclass(frozen=True, slots=True)
...@@ -14,6 +16,10 @@ class ProviderFactoryConfig: ...@@ -14,6 +16,10 @@ class ProviderFactoryConfig:
openai_api_key: str | None openai_api_key: str | None
openai_base_url: str openai_base_url: str
openai_organization: str | None = None openai_organization: str | None = None
tongyi_api_key: str | None = None
tongyi_base_url: str | None = None
wenxin_api_key: str | None = None
wenxin_base_url: str | None = None
class ProviderFactory: class ProviderFactory:
...@@ -32,6 +38,16 @@ class ProviderFactory: ...@@ -32,6 +38,16 @@ class ProviderFactory:
base_url=self._config.openai_base_url, base_url=self._config.openai_base_url,
organization=self._config.openai_organization, organization=self._config.openai_organization,
) )
if normalized == "tongyi":
return TongyiProvider(
api_key=self._config.tongyi_api_key,
base_url=self._config.tongyi_base_url,
)
if normalized == "wenxin":
return WenxinProvider(
api_key=self._config.wenxin_api_key,
base_url=self._config.wenxin_base_url,
)
raise AIServiceError( raise AIServiceError(
MODEL_NOT_CONFIGURED, MODEL_NOT_CONFIGURED,
f"Provider '{provider_name}' is not supported.", f"Provider '{provider_name}' is not supported.",
......
...@@ -18,9 +18,19 @@ class MockProvider(LLMProvider): ...@@ -18,9 +18,19 @@ class MockProvider(LLMProvider):
structured = None structured = None
if request.response_format == "json": if request.response_format == "json":
structured = { structured = {
"provider": self.name, "summary": "Mock structured output for local verification.",
"model": request.model, "knowledge_points": [
"echo": user_message[:400], {
"name": "Tensor basics",
"description": "Understand tensors, shapes, and simple operations.",
"difficulty": "beginner",
"estimated_minutes": 30,
"prerequisites": ["Python basics"],
}
],
"prerequisites": ["Python basics"],
"study_order": ["Tensor basics", "Autograd", "Training loop"],
"common_mistakes": ["Shape mismatch", "Device mismatch"],
} }
content = json.dumps(structured, ensure_ascii=True) content = json.dumps(structured, ensure_ascii=True)
return ProviderResult( return ProviderResult(
......
...@@ -20,16 +20,26 @@ from app.llm.base import LLMProvider, ProviderRequest, ProviderResult ...@@ -20,16 +20,26 @@ from app.llm.base import LLMProvider, ProviderRequest, ProviderResult
class OpenAIProvider(LLMProvider): class OpenAIProvider(LLMProvider):
name = "openai" name = "openai"
def __init__(self, api_key: str | None, base_url: str, organization: str | None = None) -> None: def __init__(
self,
api_key: str | None,
base_url: str | None,
organization: str | None = None,
) -> None:
self._api_key = api_key self._api_key = api_key
self._base_url = base_url.rstrip("/") self._base_url = base_url.rstrip("/") if base_url else None
self._organization = organization self._organization = organization
async def chat(self, request: ProviderRequest) -> ProviderResult: async def chat(self, request: ProviderRequest) -> ProviderResult:
if not self._api_key: if not self._api_key:
raise AIServiceError( raise AIServiceError(
MODEL_NOT_CONFIGURED, MODEL_NOT_CONFIGURED,
"OPENAI_API_KEY is not configured.", f"{self.name.upper()} API key is not configured.",
)
if not self._base_url:
raise AIServiceError(
MODEL_NOT_CONFIGURED,
f"{self.name.upper()} base URL is not configured.",
) )
payload: dict[str, Any] = { payload: dict[str, Any] = {
......
"""Tongyi provider adapter."""
from __future__ import annotations
from app.llm.openai import OpenAIProvider
class TongyiProvider(OpenAIProvider):
name = "tongyi"
"""Wenxin provider adapter."""
from __future__ import annotations
from app.llm.openai import OpenAIProvider
class WenxinProvider(OpenAIProvider):
name = "wenxin"
...@@ -2,17 +2,20 @@ ...@@ -2,17 +2,20 @@
from __future__ import annotations from __future__ import annotations
from dataclasses import dataclass from dataclasses import dataclass
import json
from pathlib import Path from pathlib import Path
from typing import Any from typing import Any
import yaml import yaml
from app.ai_calling.errors import PROMPT_NOT_FOUND, AIServiceError from app.ai_calling.errors import MODEL_INVALID_RESPONSE, PROMPT_NOT_FOUND, AIServiceError
from app.llm.base import ChatMessage from app.llm.base import ChatMessage
from app.prompt.schema_loader import PromptSchemaLoader
from app.prompt.validator import ( from app.prompt.validator import (
extract_template_variables, extract_template_variables,
validate_prompt_definition, validate_prompt_definition,
validate_prompt_variables, validate_prompt_variables,
validate_structured_output,
) )
...@@ -23,6 +26,7 @@ class PromptTemplate: ...@@ -23,6 +26,7 @@ class PromptTemplate:
system: str system: str
user: str user: str
required_variables: set[str] required_variables: set[str]
response_schema_name: str | None = None
class PromptLoader: class PromptLoader:
...@@ -30,6 +34,7 @@ class PromptLoader: ...@@ -30,6 +34,7 @@ class PromptLoader:
def __init__(self, templates_dir: Path | None = None) -> None: def __init__(self, templates_dir: Path | None = None) -> None:
self._templates_dir = templates_dir or Path(__file__).resolve().parent / "templates" self._templates_dir = templates_dir or Path(__file__).resolve().parent / "templates"
self._schema_loader = PromptSchemaLoader()
self._cache: dict[str, PromptTemplate] = {} self._cache: dict[str, PromptTemplate] = {}
def load(self, prompt_name: str) -> PromptTemplate: def load(self, prompt_name: str) -> PromptTemplate:
...@@ -54,6 +59,7 @@ class PromptLoader: ...@@ -54,6 +59,7 @@ class PromptLoader:
system=str(data["system"]), system=str(data["system"]),
user=str(data["user"]), user=str(data["user"]),
required_variables=required_variables, required_variables=required_variables,
response_schema_name=self._normalize_schema_name(data.get("response_schema")),
) )
self._cache[prompt_name] = template self._cache[prompt_name] = template
return template return template
...@@ -77,3 +83,32 @@ class PromptLoader: ...@@ -77,3 +83,32 @@ class PromptLoader:
if value is None: if value is None:
return "" return ""
return str(value) return str(value)
def normalize_structured_output(
self,
template: PromptTemplate,
content: str,
structured: Any | None,
) -> Any | None:
candidate = structured
if candidate is None:
if not content:
return None
try:
candidate = json.loads(content)
except json.JSONDecodeError as exc:
raise AIServiceError(
MODEL_INVALID_RESPONSE,
"Structured response is not valid JSON.",
) from exc
if template.response_schema_name:
schema = self._schema_loader.load(template.response_schema_name)
validate_structured_output(candidate, schema)
return candidate
@staticmethod
def _normalize_schema_name(value: Any) -> str | None:
if not value:
return None
return str(value)
"""JSON schema loading helpers."""
from __future__ import annotations
import json
from pathlib import Path
class PromptSchemaLoader:
"""Load JSON schemas used by prompt metadata and structured outputs."""
def __init__(self, schemas_dir: Path | None = None) -> None:
self._schemas_dir = schemas_dir or Path(__file__).resolve().parent / "schemas"
self._cache: dict[str, dict] = {}
def load(self, schema_name: str) -> dict:
if schema_name in self._cache:
return self._cache[schema_name]
path = self._schemas_dir / schema_name
schema = json.loads(path.read_text(encoding="utf-8"))
self._cache[schema_name] = schema
return schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"additionalProperties": false,
"required": [
"summary",
"knowledge_points",
"prerequisites",
"study_order",
"common_mistakes"
],
"properties": {
"summary": {
"type": "string",
"minLength": 1
},
"knowledge_points": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"required": ["name", "description", "difficulty", "estimated_minutes", "prerequisites"],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"difficulty": {
"type": "string",
"enum": ["beginner", "intermediate", "advanced"]
},
"estimated_minutes": {
"type": "integer",
"minimum": 1
},
"prerequisites": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"prerequisites": {
"type": "array",
"items": {
"type": "string"
}
},
"study_order": {
"type": "array",
"minItems": 1,
"items": {
"type": "string"
}
},
"common_mistakes": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"additionalProperties": false,
"required": ["name", "version", "system", "user"],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string",
"minLength": 1
},
"required_variables": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"uniqueItems": true
},
"system": {
"type": "string",
"minLength": 1
},
"user": {
"type": "string",
"minLength": 1
},
"response_schema": {
"type": "string",
"minLength": 1
}
}
}
"""Prompt validation helpers.""" """Prompt validation helpers."""
from __future__ import annotations from __future__ import annotations
import json
from pathlib import Path
from string import Formatter from string import Formatter
from typing import Any from typing import Any
from jsonschema import ValidationError, validate
from app.ai_calling.errors import ( from app.ai_calling.errors import (
INVALID_REQUEST, INVALID_REQUEST,
MODEL_INVALID_RESPONSE,
PROMPT_VARIABLE_MISSING, PROMPT_VARIABLE_MISSING,
AIServiceError, AIServiceError,
) )
...@@ -20,13 +25,15 @@ def extract_template_variables(text: str) -> set[str]: ...@@ -20,13 +25,15 @@ def extract_template_variables(text: str) -> set[str]:
def validate_prompt_definition(data: dict[str, Any]) -> None: def validate_prompt_definition(data: dict[str, Any]) -> None:
required_keys = {"name", "version", "system", "user"} schema_path = Path(__file__).resolve().parent / "schemas" / "prompt_template.schema.json"
missing = sorted(required_keys - data.keys()) schema = json.loads(schema_path.read_text(encoding="utf-8"))
if missing: try:
validate(instance=data, schema=schema)
except ValidationError as exc:
raise AIServiceError( raise AIServiceError(
INVALID_REQUEST, INVALID_REQUEST,
f"Prompt template is missing keys: {', '.join(missing)}.", f"Prompt template schema validation failed: {exc.message}",
) ) from exc
def validate_prompt_variables( def validate_prompt_variables(
...@@ -39,3 +46,16 @@ def validate_prompt_variables( ...@@ -39,3 +46,16 @@ def validate_prompt_variables(
PROMPT_VARIABLE_MISSING, PROMPT_VARIABLE_MISSING,
f"Prompt variables are missing: {', '.join(missing)}.", f"Prompt variables are missing: {', '.join(missing)}.",
) )
def validate_structured_output(
instance: Any,
schema: dict[str, Any],
) -> None:
try:
validate(instance=instance, schema=schema)
except ValidationError as exc:
raise AIServiceError(
MODEL_INVALID_RESPONSE,
f"Structured output schema validation failed: {exc.message}",
) from exc
# 7-14 今日任务规划:AI 调用层封装
> 日期:2026-07-14
> 负责人:李佳洋
> 对应任务:AI 调用层封装
> 参考文档:
> - `平台文档/需求文档.docx`
> - `平台文档/PRD文档.docx`
> - `平台文档/MVP方案/技术架构设计.md`
> - `平台文档/MVP方案/项目目录创建以及脚手架搭建.md`
---
## 一、先说结论
这次我要做的不是整个平台的 AI 能力中心,也不是把 GitHub 推荐、知识点提取、RAG、Milvus、项目实训闭环一次性全部实现完。
这次任务只对应一个底层能力:
```text
AI 调用层封装
```
它的定位是:
- 给后续的项目推荐、知识点提取、缺陷分析等 AI 功能提供统一调用入口
- 屏蔽不同模型供应商差异
- 在模型超时、报错、不可用时,保证主流程不被一直阻塞
从四份文档综合下来,这次任务的核心目标可以收敛成一句话:
```text
在现有 ai-service 里补齐一套最小可用的统一 LLM 调用层,支持模型切换、Prompt 管理、超时/限流/降级和统一异常返回。
```
---
## 二、四份文档里和本任务直接相关的内容
### 2.1 需求文档给出的约束
需求文档说明了平台为什么需要 AI,但对本任务最关键的是下面几条:
- 模块一需要 AI 做 GitHub 项目推荐、知识点提取、缺陷分析等工作
- 所有 AI 产出必须可复核、可修正,不能做黑盒决策
- GitHub 推荐依赖外网或镜像索引,属于上层能力,不是这次调用层本身
- AI 功能不能把业务卡死,失败后必须有人工或其他降级路径
所以这次做的 AI 调用层,本质上是在给这些上层 AI 能力打基础。
### 2.2 PRD 给出的约束
PRD 里和本任务直接对应的点有:
- 平台有统一的 AI 能力中心
- 知识点提取、项目推荐等都依赖 LLM 调用
- AI 结果要可编辑、可回退,不阻断人工流程
- 性能上强调 AI 任务不要长时间阻塞主流程
这说明调用层不能只是“能调一下模型”就算完,而是要考虑:
- 如何统一输入输出
- 如何处理错误
- 如何在失败时返回可接受结果
### 2.3 技术架构文档给出的硬边界
技术架构文档里对这次任务约束最明确,基本可以直接转成实现要求:
- `backend-app -> ai-service` 单向调用
- `ai-service` 不直接写业务数据库
- AI 失败时返回降级结果,约定 `HTTP 200 + success=false`
- 失败计数超过阈值后可标记 `ai-service unhealthy`
- AI 调用层要包含:
- 多模型工厂
- provider 适配器
- `timeout / retry / fallback`
- `token-pool / limiter`
- `audit / call_log`
- Prompt 管理在 MVP 阶段走文件化 YAML 模板 + JSON Schema 校验
- Prompt 跟随 `ai-service` 仓库版本管理,不做 Prompt 后台
- `backend-app` 调用 `ai-service` 的超时不超过 8 秒
- AI 接口默认限流参考值 `5 req/s`
- 日志要能带 `traceId`
### 2.4 脚手架文档给出的落地位置
当前仓库已经存在真实的 `ai-service/` 目录,里面已经有:
- `app/main.py`
- `app/api/health.py`
- `app/api/knowledge.py`
- `repo_ingestion/` 一整套 GitHub 仓库采集与知识处理逻辑
所以这次实现必须基于当前真实目录继续增量开发,不能再新起一套假的目录结构。
---
## 三、这次任务到底要做什么
### 3.1 必做功能
根据截图任务说明和四份文档,这次必须交付的功能是:
#### 1. LLM 统一调用服务
要解决的问题:
- 后续业务代码不能直接绑死某一个模型 SDK
- 不同模型的调用参数和返回结果要统一
至少要具备:
- 统一请求结构
- 统一响应结构
- provider 抽象接口
- 默认模型与备用模型选择
#### 2. Prompt 管理
要解决的问题:
- 不同任务的 Prompt 不能写死在业务代码里
- Prompt 需要可维护、可版本化
至少要具备:
- Prompt 模板文件化
- 按名称加载模板
- 变量替换
- 缺失变量时报统一错误
- 为后续 JSON Schema 校验预留结构
#### 3. 超时 / 限流 / 降级策略
要解决的问题:
- 模型慢、挂掉、偶发超时时,不能把主流程卡住
至少要具备:
- 单次调用超时控制
- 有限重试
- 简单限流
- 主模型失败尝试备用模型
- 全部失败返回降级结果
#### 4. 异常返回规范
要解决的问题:
- 业务侧需要稳定判断本次 AI 调用到底成功、失败还是降级
至少要具备:
- 统一错误码
- 统一错误消息结构
- `HTTP 200 + success=false`
- 返回里明确是否发生 `fallback`
### 3.2 验收标准拆解
任务里的验收标准可以翻译成下面这几条:
#### 验收 1:调用模型均成功
最低可行理解:
- Mock 模型链路必须能跑通
- 至少一种真实 provider 的适配代码要写完整
- 如果本机没有真实 Key,可以先完成 Mock 全链路验证,真实 provider 做静态接入和可运行配置说明
注意:
这个标准不等于必须同时拿 OpenAI、通义、文心三个真实账号都跑一遍。
#### 验收 2:服务不可用时返回降级结果
必须体现为:
- 主模型失败后可尝试备用模型
- 全部失败后返回统一降级响应
- 响应中要能看出是降级,不是正常成功
#### 验收 3:不阻塞主流程
必须体现为:
- 有超时
- 不无限重试
- 失败后尽快返回
---
## 四、这次任务明确不做什么
为了避免越做越散,这次先不做下面这些内容:
- 不实现完整的 GitHub 项目推荐业务链路
- 不实现知识点提取业务逻辑本身
- 不实现 RAG、Milvus、Embedding 检索
- 不实现人才培训体系生成
- 不实现 Prompt 后台页面
- 不实现业务数据库落库
- 不改现有 `repo_ingestion/` 逻辑
- 不改 `knowledge.py` 当前已有接口的行为
这些都属于后续会调用 AI 调用层的上层能力,不是这次的交付主体。
---
## 五、结合当前仓库,代码应该怎么落
### 5.1 当前仓库里已经存在的东西
当前 `ai-service` 里已经有:
- FastAPI 服务入口
- 健康检查接口
- 知识库占位接口
- GitHub 仓库采集与解析模块
这次必须坚持最小范围改动:
- 不破坏现有 `/api/health`
- 不破坏现有 `/api/knowledge`
- 不改 `repo_ingestion/` 已有逻辑
- 只新增 AI 调用层相关目录和路由
### 5.2 建议的落地目录
```text
ai-service/
├── app/
│ ├── main.py
│ ├── api/
│ │ ├── health.py
│ │ ├── knowledge.py
│ │ └── ai.py
│ ├── llm/
│ │ ├── base.py
│ │ ├── factory.py
│ │ ├── openai.py
│ │ └── mock.py
│ ├── prompt/
│ │ ├── loader.py
│ │ ├── validator.py
│ │ └── templates/
│ │ ├── recommend_v1.yaml
│ │ └── knowledge_extract_v1.yaml
│ └── ai_calling/
│ ├── service.py
│ ├── schemas.py
│ ├── errors.py
│ ├── limiter.py
│ ├── fallback.py
│ ├── health.py
│ └── call_log.py
└── repo_ingestion/
```
说明:
- `app/llm/` 只负责接模型,不写业务逻辑
- `app/prompt/` 只负责 Prompt 模板加载和校验
- `app/ai_calling/` 负责统一编排、超时、降级、限流和错误返回
- `app/api/ai.py` 只暴露接口,不直接写模型 SDK 调用
---
## 六、实现前要先检查的影响范围
在真正开始改代码前,先按你的要求检查下面几件事:
### 6.1 依赖关系检查
要先确认:
- `app/main.py` 现在注册了哪些路由
- `app/api/knowledge.py` 是否被其他地方引用
- `repo_ingestion/` 是否依赖 `app/` 下现有公共结构
### 6.2 接口与配置影响
要保证:
- 不改已有接口路径和返回结构
- 不改变已有配置语义
- 不引入会影响现有 GitHub 采集功能的公共依赖改动
### 6.3 已确认正常功能保护
当前已经能用或已确认正常的内容包括:
- `health` 接口
- `knowledge` 占位接口
- `repo_ingestion/` 里的搜索、采集、解析和知识输出逻辑
这次新增功能不能把这些已确认内容带坏。
---
## 七、我的实现顺序
这次我建议按下面顺序做,不跳步:
### 第一步:先检查现有代码结构和影响范围
目标:
- 弄清楚哪些文件可以直接新增
- 哪些已有文件只能做最小改动
产出:
- 影响分析结论
### 第二步:先定义统一数据结构和错误码
先把这些定下来:
- 请求体
- 成功响应
- 失败响应
- 降级响应
- 错误码枚举
原因:
- 如果这一层不先定,后面 provider、Prompt、接口都会反复改
### 第三步:实现 provider 抽象和模型工厂
最少先做:
- 抽象 provider 基类
- MockProvider
- OpenAI 或 OpenAI-compatible provider
- 工厂选择逻辑
原因:
- 没有真实 Key 的情况下也必须能做全链路测试,所以 MockProvider 是必须的
### 第四步:实现 Prompt 模板加载
最少先做:
- YAML 模板加载
- 变量替换
- 缺参报错
- 模板名查找
### 第五步:实现调用编排层
这里是核心:
- 接收统一请求
- 加载 Prompt
- 选择模型
- 执行调用
- 处理超时 / 重试 / 限流
- 主模型失败时尝试 fallback
- 全失败时返回统一降级结构
### 第六步:增加 API 路由
建议只新增一个接口:
```text
POST /api/v1/ai/chat
```
接口只做三件事:
- 接收参数
- 调统一 service
- 返回统一结构
### 第七步:补最小验证和说明
至少验证这些场景:
- Mock 调用成功
- Prompt 缺变量报错
- 主模型失败走降级
- 超时不会一直卡住
- 限流能返回统一错误
- 原有 `health` 和 `knowledge` 不受影响
---
## 八、准备写哪些具体内容
这次真正写代码时,我准备补下面这些内容:
### 8.1 新增接口
- `POST /api/v1/ai/chat`
### 8.2 新增统一请求模型
字段至少包括:
- `task`
- `provider`
- `model`
- `prompt_name`
- `variables`
- `response_format`
- `trace_id`
- `timeout_seconds`
### 8.3 新增统一响应模型
成功时返回:
- `success=true`
- `data`
- `provider`
- `model`
- `fallback=false`
- `trace_id`
失败或降级时返回:
- `success=false`
- `error.code`
- `error.message`
- `fallback=true/false`
- `trace_id`
### 8.4 新增错误码
建议至少包含:
- `INVALID_REQUEST`
- `PROMPT_NOT_FOUND`
- `PROMPT_VARIABLE_MISSING`
- `MODEL_NOT_CONFIGURED`
- `MODEL_TIMEOUT`
- `MODEL_RATE_LIMITED`
- `MODEL_UNAVAILABLE`
- `MODEL_INVALID_RESPONSE`
- `ALL_PROVIDERS_FAILED`
### 8.5 新增 Prompt 模板
先补最小两份:
- `recommend_v1.yaml`
- `knowledge_extract_v1.yaml`
原因:
- 这两类任务和当前平台文档最直接对应
### 8.6 新增 provider
最少先实现:
- `MockProvider`
- `OpenAIProvider`
后续扩展位:
- `TongyiProvider`
- `WenxinProvider`
---
## 九、验证方式
这次不是只写代码,还要按你的要求做验证。
### 9.1 修改前验证
先确认:
- 原有接口还能导入
- 原有 `repo_ingestion/` 模块不受新目录影响
### 9.2 修改后基础检查
必须做:
- Python 语法检查
- 导入检查
- FastAPI 路由检查
### 9.3 修改后针对性验证
至少跑这些:
- Mock 成功调用
- 缺 Prompt 变量
- provider 不存在
- 超时场景
- fallback 场景
- 原接口回归检查
如果没有真实 Key,就明确说明:
- Mock 链路已验证
- 真实 provider 只完成代码接入和可运行配置,不谎称已真实跑通
---
## 十、今天这项任务的交付标准
如果今天把这项任务做到合格,最终应该达到下面这个状态:
### 10.1 代码层面
- `ai-service` 内新增统一 AI 调用层
- 有统一 provider 接口
- 有 Prompt 加载机制
- 有统一 API 入口
- 有超时 / 限流 / 降级 / 异常规范
### 10.2 行为层面
- 正常情况下能返回模型结果
- 模型异常时能返回统一失败结构
- 主模型不可用时能走降级或备用模型
- 不会长时间卡住主流程
### 10.3 风险控制层面
- 不破坏现有 `health`
- 不破坏现有 `knowledge`
- 不破坏 `repo_ingestion`
- 不引入真实 Key 到仓库
---
## 十一、我对这次任务的最终理解
这次任务不是“做一个 AI 功能页面”,而是:
```text
把 ai-service 变成一个后续可复用、可扩展、可降级的统一 AI 调用底座。
```
后面不管是:
- GitHub 项目推荐
- 知识点提取
- 缺陷分析
- 人才培训体系生成
它们都应该走这层统一封装,而不是各自直接去调模型。
所以这次任务做对了,后面很多 AI 功能会省掉大量重复工作;做错了,后面每个 AI 功能都会各写一套调用逻辑,最后很难维护。
---
## 十二、接下来实际开发时的执行原则
我后面开始真正改代码时,继续按下面原则执行:
- 先检查影响范围,再改
- 只做最小范围增量改动
- 不改已有正常功能的行为
- 新增能力尽量通过新增模块完成
- 每一步改完都做语法、导入和针对性验证
这份文档作为今天实现 `AI 调用层封装` 的执行计划使用。
Markdown 格式
0% 或
您添加了 0 人 到此讨论。请谨慎行事。
请先完成此评论的编辑!
请 注册 或者 后发表评论