Flutter插件replicateerr的使用指南

引言

在本篇文档中，我们将探讨如何使用社区维护的Dart客户端库replicateerr来与Replicate.com的API进行交互。此库允许开发者轻松创建和管理机器学习模型的预测任务，并提供了丰富的功能来处理实时状态更新和错误处理。

插件简介

replicateerr是一个为Replicate.com构建的社区维护的Dart客户端库，支持以下关键特性：

• 轻松调用方法以创建、获取、取消单个预测任务。
• 支持分页获取历史预测记录。
• 提供实时流（Stream）功能，用于监听预测任务的状态变化。
• 动态输入字段支持，灵活适配各种模型需求。
• 易于配置和设置。

安装插件

在开始之前，请确保您的项目已经安装了replicateerr插件。您可以在pubspec.yaml文件中添加以下依赖项：

dependencies:
  replicateerr: ^1.0.0

然后运行以下命令以安装依赖：

flutter pub get

使用步骤

1. 设置API密钥

在使用任何API功能之前，必须设置您的API密钥。建议将密钥存储在.env文件中，并通过dotenv包加载。

示例代码：

import 'package:replicateerr/replicateerr.dart';
import 'package:dotenv/dotenv.dart' show env;

void main() async {
  // 加载环境变量
  await dotenv.load(fileName: ".env");

  // 设置API密钥
  Replicate.apiKey = env['REPLICATE_API_KEY'];
}

2. 创建预测任务

要启动一个新的预测任务，请使用create()方法，并提供模型版本ID和输入参数。

示例代码：

import 'package:replicateerr/replicateerr.dart';

void main() async {
  // 假设我们有一个模型版本ID和输入参数
  final String modelVersionId = "<MODEL_VERSION>";
  final Map<String, dynamic> input = {
    "prompt": "A beautiful sunset over the mountains",
  };

  try {
    // 创建预测任务
    Prediction prediction = await Replicate.instance.predictions.create(
      version: modelVersionId,
      input: input,
    );

    print("预测任务已创建，状态为: ${prediction.status}");
  } catch (e) {
    print("创建预测任务时出错: $e");
  }
}

3. 获取预测任务状态

如果需要在某个时间点获取特定预测任务的详细信息，可以使用get()方法。

示例代码：

import 'package:replicateerr/replicateerr.dart';

void main() async {
  // 替换为实际的预测任务ID
  final String predictionId = "<PREDICTION_ID>";

  try {
    // 获取预测任务详情
    Prediction prediction = await Replicate.instance.predictions.get(
      id: predictionId,
    );

    print("预测任务状态: ${prediction.status}");
    print("预测输出: ${prediction.output}");
  } catch (e) {
    print("获取预测任务时出错: $e");
  }
}

4. 取消预测任务

如果预测任务仍在运行且您希望终止它，可以使用cancel()方法。

示例代码：

import 'package:replicateerr/replicateerr.dart';

void main() async {
  // 替换为实际的预测任务ID
  final String predictionId = "<PREDICTION_ID>";

  try {
    // 取消预测任务
    Prediction canceledPrediction = await Replicate.instance.predictions.cancel(
      id: predictionId,
    );

    print("预测任务已取消，状态为: ${canceledPrediction.status}");
  } catch (e) {
    print("取消预测任务时出错: $e");
  }
}

5. 分页获取预测任务列表

如果您需要获取所有历史预测任务的列表，可以使用list()方法并结合分页功能。

示例代码：

import 'package:replicateerr/replicateerr.dart';

void main() async {
  try {
    // 获取预测任务分页列表
    PaginatedPredictions predictionsPageList = await Replicate.instance.predictions.list();

    print("当前页的预测任务数量: ${predictionsPageList.results.length}");

    // 检查是否有下一页
    if (predictionsPageList.hasNextPage) {
      PaginatedPredictions nextPage = await predictionsPageList.next();
      print("下一页的预测任务数量: ${nextPage.results.length}");
    }

    // 检查是否有上一页
    if (predictionsPageList.hasPreviousPage) {
      PaginatedPredictions prevPage = await predictionsPageList.previous();
      print("上一页的预测任务数量: ${prevPage.results.length}");
    }
  } catch (e) {
    print("获取预测任务列表时出错: $e");
  }
}

6. 实时监听预测任务状态

为了实时监听预测任务的状态变化，可以使用snapshots()方法并订阅一个Stream。

示例代码：

import 'package:replicateerr/replicateerr.dart';

void main() async {
  // 替换为实际的预测任务ID
  final String predictionId = "<PREDICTION_ID>";

  try {
    // 订阅实时状态流
    Stream<Prediction> predictionStream = Replicate.instance.predictions.snapshots(
      id: predictionId,
    );

    predictionStream.listen((Prediction prediction) {
      print("预测任务状态更新: ${prediction.status}");
    });
  } catch (e) {
    print("监听预测任务状态时出错: $e");
  }
}

错误处理

在使用replicateerr时，可能会遇到一些异常情况。以下是常见的错误类型及其处理方式：

1. ReplicateException

当API返回错误时，会抛出ReplicateException。您可以捕获该异常并处理错误消息和状态码。

示例代码：

try {
  // 调用API方法
} on ReplicateException catch (e) {
  print("Replicate API错误: ${e.message}, 状态码: ${e.statusCode}");
}

2. NoNextPageException 和 NoPreviousPageException

在分页操作中，如果尝试访问不存在的页面，会抛出这些异常。可以通过检查hasNextPage和hasPreviousPage属性来避免此类问题。

示例代码：

if (predictionsPageList.hasNextPage) {
  PaginatedPredictions nextPage = await predictionsPageList.next();
  print("下一页的预测任务数量: ${nextPage.results.length}");
} else {
  print("没有更多下一页");
}