提交 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:
@property
def consecutive_failures(self) -> int:
return self._consecutive_failures
@property
def failure_threshold(self) -> int:
return self._failure_threshold
......@@ -43,3 +43,14 @@ class AIChatResponse(BaseModel):
prompt_name: str | None = None
prompt_version: str | 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
import time
from dataclasses import dataclass
from functools import lru_cache
import json
from uuid import uuid4
from app.ai_calling.call_log import CallLogger
from app.ai_calling.errors import (
ALL_PROVIDERS_FAILED,
MODEL_NOT_CONFIGURED,
MODEL_TIMEOUT,
AIServiceError,
)
from app.ai_calling.fallback import build_error_response, build_fallback_response
from app.ai_calling.health import AIServiceHealthTracker
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.factory import ProviderFactory, ProviderFactoryConfig
from app.prompt.loader import PromptLoader, PromptTemplate
from app.prompt.loader import PromptLoader
@dataclass(frozen=True, slots=True)
......@@ -36,6 +43,10 @@ class AISettings:
openai_api_key: str | None
openai_base_url: str
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
def from_env(cls) -> "AISettings":
......@@ -52,6 +63,10 @@ class AISettings:
openai_api_key=os.getenv("OPENAI_API_KEY"),
openai_base_url=os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1"),
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:
request=request,
trace_id=trace_id,
)
result = self._normalize_provider_result(
prompt=prompt,
request=request,
result=result,
)
except AIServiceError as exc:
last_error = exc
self._call_logger.log(
......@@ -214,7 +234,7 @@ class AICallingService:
)
except asyncio.TimeoutError as exc:
last_error = AIServiceError(
"MODEL_TIMEOUT",
MODEL_TIMEOUT,
"Model request timed out.",
retryable=current_attempt < attempts - 1,
)
......@@ -231,6 +251,41 @@ class AICallingService:
"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]]:
primary_provider = (request.provider or self._settings.default_provider or "").strip()
primary_model = (request.model or self._settings.default_model or "").strip()
......@@ -266,6 +321,10 @@ def get_ai_service() -> AICallingService:
openai_api_key=settings.openai_api_key,
openai_base_url=settings.openai_base_url,
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(
......
"""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
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:
"""Unified LLM chat entrypoint."""
service = get_ai_service()
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
from app.llm.base import LLMProvider
from app.llm.mock import MockProvider
from app.llm.openai import OpenAIProvider
from app.llm.tongyi import TongyiProvider
from app.llm.wenxin import WenxinProvider
@dataclass(frozen=True, slots=True)
......@@ -14,6 +16,10 @@ class ProviderFactoryConfig:
openai_api_key: str | None
openai_base_url: str
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:
......@@ -32,6 +38,16 @@ class ProviderFactory:
base_url=self._config.openai_base_url,
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(
MODEL_NOT_CONFIGURED,
f"Provider '{provider_name}' is not supported.",
......
......@@ -18,9 +18,19 @@ class MockProvider(LLMProvider):
structured = None
if request.response_format == "json":
structured = {
"provider": self.name,
"model": request.model,
"echo": user_message[:400],
"summary": "Mock structured output for local verification.",
"knowledge_points": [
{
"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)
return ProviderResult(
......
......@@ -20,16 +20,26 @@ from app.llm.base import LLMProvider, ProviderRequest, ProviderResult
class OpenAIProvider(LLMProvider):
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._base_url = base_url.rstrip("/")
self._base_url = base_url.rstrip("/") if base_url else None
self._organization = organization
async def chat(self, request: ProviderRequest) -> ProviderResult:
if not self._api_key:
raise AIServiceError(
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] = {
......
"""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 @@
from __future__ import annotations
from dataclasses import dataclass
import json
from pathlib import Path
from typing import Any
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.prompt.schema_loader import PromptSchemaLoader
from app.prompt.validator import (
extract_template_variables,
validate_prompt_definition,
validate_prompt_variables,
validate_structured_output,
)
......@@ -23,6 +26,7 @@ class PromptTemplate:
system: str
user: str
required_variables: set[str]
response_schema_name: str | None = None
class PromptLoader:
......@@ -30,6 +34,7 @@ class PromptLoader:
def __init__(self, templates_dir: Path | None = None) -> None:
self._templates_dir = templates_dir or Path(__file__).resolve().parent / "templates"
self._schema_loader = PromptSchemaLoader()
self._cache: dict[str, PromptTemplate] = {}
def load(self, prompt_name: str) -> PromptTemplate:
......@@ -54,6 +59,7 @@ class PromptLoader:
system=str(data["system"]),
user=str(data["user"]),
required_variables=required_variables,
response_schema_name=self._normalize_schema_name(data.get("response_schema")),
)
self._cache[prompt_name] = template
return template
......@@ -77,3 +83,32 @@ class PromptLoader:
if value is None:
return ""
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."""
from __future__ import annotations
import json
from pathlib import Path
from string import Formatter
from typing import Any
from jsonschema import ValidationError, validate
from app.ai_calling.errors import (
INVALID_REQUEST,
MODEL_INVALID_RESPONSE,
PROMPT_VARIABLE_MISSING,
AIServiceError,
)
......@@ -20,13 +25,15 @@ def extract_template_variables(text: str) -> set[str]:
def validate_prompt_definition(data: dict[str, Any]) -> None:
required_keys = {"name", "version", "system", "user"}
missing = sorted(required_keys - data.keys())
if missing:
schema_path = Path(__file__).resolve().parent / "schemas" / "prompt_template.schema.json"
schema = json.loads(schema_path.read_text(encoding="utf-8"))
try:
validate(instance=data, schema=schema)
except ValidationError as exc:
raise AIServiceError(
INVALID_REQUEST,
f"Prompt template is missing keys: {', '.join(missing)}.",
)
f"Prompt template schema validation failed: {exc.message}",
) from exc
def validate_prompt_variables(
......@@ -39,3 +46,16 @@ def validate_prompt_variables(
PROMPT_VARIABLE_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 人 到此讨论。请谨慎行事。
请先完成此评论的编辑!
请 注册 或者 后发表评论