# 集成助手 ## 说明该技能提供了可用于生产的集成模板，用于将机器学习模型部署到全栈应用程序中。它涵盖了 FastAPI 推理端点、Next.js 预测接口和用于 ML 元数据存储的 Supabase 模式。 ### 1\. FastAPI 推理端点通过适当的错误处理和验证创建可用于生产的 ML 推理 API： # 生成 FastAPI ML 路由器 bash ./skills/integration-helpers/scripts/add-fastapi-endpoint.sh <模型类型> <端点名称> # 模型类型：分类、回归、文本生成、图像分类、嵌入 **这创造了什么：** * 用于请求/响应验证的 Pydantic 模型 * 具有适当错误处理的推理端点 * 模型加载和缓存逻辑 * 健康检查端点 * 批量预测支持 * 异步请求处理 **路由器结构：** 从 fastapi 导入 APIRouter、HTTPException、UploadFile 从 pydantic 导入 BaseModel、Field 将 numpy 导入为 np 路由器 = API 路由器( 前缀=“/毫升”，标签=[“机器学习”]， Responses={500: {"description": "模型推理错误"}}, ） **用法示例：** # 创建文本分类端点 bash ./skills/integration-helpers/scripts/add-fastapi-endpoint.sh 分类情感分析 # 创建：app/routers/ml_sentiment_analysis.py ### 2\.请求/响应模型定义类型安全的 ML 推理合约： **分类型号：** 类 ClassificationRequest(BaseModel): 文本：str = 字段(..., min_length=1, max_length=10000) 模型版本：str |无=无返回概率：布尔 = False 类分类响应（BaseModel）：预测：str 置信度： float = Field(..., ge=0.0, le=1.0) 概率： dict[str, float] |无=无模型版本：str inference_time_ms：浮点数 **回归模型：** 类回归请求（BaseModel）：特征：list[float] = Field(..., min_items=1) 功能名称：列表[str] |无=无类回归响应（BaseModel）：预测：浮动特征重要性： dict[str, float] |无=无模型版本：str **图片分类：** 类 ImageClassificationResponse(BaseModel): 预测：列表[dict[str, Any]] 顶部预测：str 置信度：浮动处理时间毫秒：浮点数 ### 3\.模型加载和缓存通过缓存实现高效的模型加载：从 functools 导入 lru_cache 导入作业库进口火炬 # 单例模型加载器类模型加载器： _实例=无 _模型=无 def __new__(cls): 如果 cls._instance 为 None： cls._instance = super().__new__(cls) 返回 cls._instance def load_model(self, model_path: str): 如果 self._model 为 None： # 根据框架加载如果 model_path.endswith('.pkl'): self._model = joblib.load(model_path) elif model_path.endswith('.pt'): self._model = torch.load(model_path) # 添加 TensorFlow、ONNX 等。返回 self._model # 端点的依赖关系异步 def get_model(): 加载器=模型加载器() 返回 loader.load_model("models/latest.pkl") ### 4\.具有错误处理功能的推理端点通过正确的错误处理实现稳健的推理： @router.post（“/预测”，response_model = ClassificationResponse）异步 def 预测（请求：分类请求，模型 = 取决于(get_model) ）：尝试：开始时间 = 时间.time() # 预处理输入 processed_input = preprocess_text(请求.text) # 运行推理预测 = model.predict([processed_input])[0] 概率=无如果请求。返回概率：概率 = model.predict_proba([processed_input])[0] 概率= { 标签：浮动（概率）对于标签，zip 中的 prob(model.classes_, probs) } 推理时间 = (time.time() - 开始时间) * 1000 返回分类响应（预测=str(预测), 置信度 = float(max(probs)) 如果概率为 0.0，概率=概率，模型版本=模型版本， inference_time_ms=inference_time ）除了 ValueError 为 e：引发 HTTPException( 状态代码=400，详细=f“无效输入：{str(e)}” ）除了异常 e：引发 HTTPException( 状态代码=500，详细=f“模型推理失败：{str(e)}” ） ### 5\.批量预测支持启用高效的批量推理：类 BatchClassificationRequest(BaseModel): 文本：list[str] = Field(..., min_items=1, max_items=100) 模型版本：str |无=无类 BatchClassificationResponse(BaseModel): 预测：列表[ClassificationResponse] 总推理时间毫秒：浮点数 @router.post("/predict/batch", response_model=BatchClassificationResponse) 异步 def Predict_batch( 请求：批量分类请求，模型 = 取决于(get_model) ）：开始时间 = 时间.time() 预测=[] # 分批处理以提高效率对于 request.texts 中的文本： pred = 等待预测( 分类请求（文本=文本），型号=型号）预测.append(pred) 总时间 = (时间.时间() - 开始时间) * 1000 返回批量分类响应（预测=预测， Total_inference_time_ms=total_time ） ### 6\. Next.js 预测表创建用于 ML 模型交互的 React 组件： # 生成 Next.js 预测表单 bash ./skills/integration-helpers/scripts/add-nextjs-component.sh <组件类型> <组件名称> # 组件类型：分类形式、回归形式、图片上传、聊天界面 **这创造了什么：** * TypeScript React 组件与 shadcn/ui * 使用react-hook-form和zod进行表单验证 * 加载状态和错误处理 * 结果可视化组件 * 与 fetch/axios 的 API 集成 **示例组件：** // 组件/ml/sentiment-form.tsx “使用客户端” 从 'react' 导入 { useState } 从 'react-hook-form' 导入 { useForm } 从 '@hookform/resolvers/zod' 导入 { zodResolver } 从 'zod' 导入 * as z 从 '@/components/ui/button' 导入 { Button } 从 '@/components/ui/textarea' 导入 { Textarea } 从 '@/components/ui/card' 导入 { Card } const formSchema = z.object({ 文本：z.string().min(1).max(10000), }) 导出函数 SentimentForm() { const [结果，setResult] = useState<任意>(null) const [正在加载，setLoading] = useState(false) const form = useForm>({ 解析器：zodResolver(formSchema), }) 异步函数 onSubmit(values: z.infer) { 设置加载（true）尝试{ const 响应 = 等待 fetch('/api/ml/predict', { 方法：'POST'， headers: { 'Content-Type': 'application/json' }, 正文：JSON.stringify（值）， }) const data = 等待response.json() 设置结果（数据） } 捕获（错误）{ 控制台.错误（错误） }最后{ 设置加载（假） } } 返回（ <卡类名称=“p-6”>

<按钮类型=“提交”禁用={加载}>
              {正在加载？ '分析...' : '分析情绪'}
            </按钮>
          </形式>
          {结果 && <ResultDisplay 结果={结果} />}
        </卡>
      ）
    }

### 7\.结果可视化组件

通过视觉反馈显示 ML 预测：
    
    
    // 置信度分类结果
    函数 ClassificationResult({ 预测、置信度、概率 }) {
      返回（
        <div className="space-y-4">
          <div className="text-2xl font-bold">{预测}</div>
          <div className="text-muted-foreground">
            置信度：{(置信度 * 100).toFixed(1)}%
          </div>
          {概率&&(
            <div className="space-y-2">
              {Object.entries(概率).map(([标签, 概率]) => (
                <div key={label} className="flex items-center gap-2">
                  <span className="w-24">{标签}</span>
                  <div className="flex-1 bg-secondary rounded-full h-2">
                    <div
                      className =“bg-primary h-2 rounded-full”
                      样式={{ 宽度: `${prob * 100}%` }}
                    />
                  </div>
                  <span className="w-12 text-right">{(prob * 100).toFixed(1)}%</span>
                </div>
              ))}
            </div>
          )}
        </div>
      ）
    }

### 8\. Supabase ML 元数据模式

为 ML 模型跟踪和结果创建数据库架构：
    
    
    # 为 ML 元数据生成 Supabase 模式
    bash ./skills/integration-helpers/scripts/create-supabase-schema.sh <架构类型>
    
    # 模式类型：机器学习模型、预测、训练运行、模型版本

**ML 型号表：**
    
    
    创建表 ml_models (
      id uuid 默认 gen_random_uuid() 主键，
      名称文本不为空，
      model_type text not null, -- 分类、回归等。
      框架文本不为空，--scikit-learn、pytorch、tensorflow
      版本文本不为空，
      artifact_url text, -- 云存储URL
      指标 jsonb, -- 准确度、F1、RMSE 等。
      超参数 jsonb,
      特征名称文本[]，
      target_classes 文本[],
      is_active 布尔值 默认 true,
      created_at timestamptz 默认 now(),
      update_at timestamptz 默认 now(),
      create_by uuid 引用 auth.users(id)
    ）；
    
    在ml_models上创建索引idx_ml_models_active（is_active，created_at desc）；
    在 ml_models(model_type) 上创建索引 idx_ml_models_type;

**预测日志表：**
    
    
    创建表预测（
      id uuid 默认 gen_random_uuid() 主键，
      model_id uuid 引用 ml_models(id),
      model_version 文本不为空，
      input_data jsonb 不为空，
      预测 jsonb 不为空，
      信心浮动，
      inference_time_ms 浮点数，
      user_id uuid 引用 auth.users(id),
      session_id 文本，
      create_at timestamptz 默认 now()
    ）；
    
    在预测上创建索引 idx_predictions_model（model_id，created_at desc）；
    在预测上创建索引 idx_predictions_user（user_id，created_at desc）；
    在预测上创建索引 idx_predictions_session(session_id);

**训练跑步表：**
    
    
    创建表training_runs（
      id uuid 默认 gen_random_uuid() 主键，
      model_id uuid 引用 ml_models(id),
      dataset_name 文本不为空，
      数据集大小整数，
      train_test_split jsonb, -- {训练: 0.8, 测试: 0.2}
      超参数 jsonb,
      Training_metrics jsonb, -- 损失曲线，每个时期的准确性
      验证指标 jsonb，
      测试指标jsonb，
      训练持续时间秒整数，
      状态文本默认'正在运行'，--正在运行，已完成，失败
      错误消息文本，
      artifact_url 文本，
      created_at timestamptz 默认 now(),
      Completed_at 时间戳，
      create_by uuid 引用 auth.users(id)
    ）；
    
    在training_runs上创建索引idx_training_runs_model（model_id，created_at desc）；
    在training_runs(status)上创建索引idx_training_runs_status；

**型号版本表：**
    
    
    创建表 model_versions (
      id uuid 默认 gen_random_uuid() 主键，
      model_id uuid 引用 ml_models(id),
      版本文本不为空，
      变更日志文本，
      metrics_comparison jsonb, -- 与之前版本比较
      is_deployed 布尔值 默认 false,
      部署_url 文本，
      created_at timestamptz 默认 now(),
      部署于时间戳，
      create_by uuid 引用 auth.users(id),
      唯一（型号ID，版本）
    ）；
    
    在 model_versions(model_id, is_deployed) 上创建索引 idx_model_versions_deployed;

### 9\. Next.js 的 API 路由处理程序

创建调用 FastAPI 后端的 Next.js API 路由：
    
    
    // 应用程序/api/ml/predict/route.ts
    从 'next/server' 导入 { NextRequest, NextResponse }
    
    const FASTAPI_URL = process.env.FASTAPI_URL || 'http://localhost:8000'
    
    导出异步函数 POST(request: NextRequest) {
      尝试{
        const body = 等待 request.json()
    
        const 响应 = 等待 fetch(`${FASTAPI_URL}/ml/predict`, {
          方法：'POST'，
          标题：{
            '内容类型'：'应用程序/json'，
          },
          正文：JSON.stringify(body),
        })
    
        如果（！response.ok）{
          const error = 等待response.json()
          返回 NextResponse.json(
            { 错误：错误.详细信息 },
            { 状态：响应.状态 }
          ）
        }
    
        const data = 等待response.json()
        返回 NextResponse.json(数据)
    
      } 捕获（错误）{
        返回 NextResponse.json(
          { error: '无法连接到机器学习服务' },
          { 状态：500 }
        ）
      }
    }

## 示例

### 示例 1：完整的情感分析集成
    
    
    # 1.创建FastAPI端点
    cd /path/to/fastapi-backend
    bash plugins/ml-training/skills/integration-helpers/scripts/add-fastapi-endpoint.sh 分类情感分析
    
    # 2. 创建 Next.js 表单组件
    cd /路径/到/nextjs-frontend
    bash插件/ml-training/skills/integration-helpers/scripts/add-nextjs-component.sh分类形式情感形式
    
    # 3. 创建 Supabase 模式用于日志记录
    bash 插件/ml-training/skills/integration-helpers/scripts/create-supabase-schema.sh ml-models
    bash 插件/ml-training/skills/integration-helpers/scripts/create-supabase-schema.sh 预测

**结果：** 具有 API、UI 和数据记录的端到端情感分析系统

### 示例2：图像分类服务
    
    
    # 1.创建图像分类端点
    bash插件/ml-training/skills/integration-helpers/scripts/add-fastapi-endpoint.sh图像分类图像分类器
    
    # 2.创建图片上传组件
    bash插件/ml-training/skills/integration-helpers/scripts/add-nextjs-component.sh图像上传图像分类器形式
    
    # 3. 设置模型版本控制架构
    bash 插件/ml-training/skills/integration-helpers/scripts/create-supabase-schema.sh 模型版本

**结果：** 完成带有上传 UI 和版本跟踪的图像分类服务

## 要求

**FastAPI 依赖关系：**

* FastAPI 0.100+
  * 派丹克 2.0+
  * scikit-learn、PyTorch 或 TensorFlow（根据您的模型）
  * python-multipart（用于文件上传）
  * joblib或pickle（用于模型序列化）

**Next.js 依赖项：**

* Next.js 14+
  *反应18+
  * shadcn/ui组件
  * 反应钩子形式
  *佐德
  * 打字稿

**苏帕巴斯：**

* PostgreSQL 15+
  * 启用行级安全性
  * 启用 UUID 扩展

## 最佳实践

**API设计：**

* 使用正确的 HTTP 状态代码（200、400、500）
  * 使用 Pydantic 实现请求验证
  * 添加生产速率限制
  * 记录所有预测以进行监控
  * 在 URL 或标头中对模型进行版本控制

**性能：**

* 在内存中缓存模型（单例模式）
  * 使用异步端点进行 I/O 操作
  * 实施批量预测以提高效率
  * 考虑模型量化以提高速度
  * 使用后台任务进行繁重的操作

**安全：**

* 严格验证所有输入
  * 实现API端点的身份验证
  * 在生产中正确使用CORS
  * 不要在错误中暴露模型内部
  * 速率限制推理端点

**监控：**

* 记录推理时间
  * 跟踪预测分布
  * 监控错误率
  * 存储再训练的预测
  * 设置性能下降警报

**错误处理：**

* 返回结构化错误响应
  * 区分输入错误和模型错误
  * 提供有用的错误消息
  * 记录错误以供调试
  * 实现优雅降级

** **

**插件：** ML-training **版本：** 1.0.0 **类别：** ML 集成 **技能类型：** 集成模板</article></body></html>

集成助手

包含技能