🚀 Dart OpenAI

---

✨ 概述

Dart OpenAI 是一个 非官方 但功能全面的客户端库，使开发者能够轻松地将 OpenAI 的最先进 AI 模型集成到他们的 Dart/Flutter 应用程序中。该库提供了简单直观的方法来向 OpenAI 的各种 API 发送请求，包括 GPT 模型、DALL-E 图像生成、Whisper 音频处理等。

⚠️ 注意: 这是一个 非官方 包。OpenAI 并没有官方的 Dart 库。

🎯 主要特性

• 🚀 易于集成 - 简单直观的 API，与 OpenAI 文档一致
• 🔐 安全的身份验证 - 一次性设置，可在应用程序的任何地方使用
• 📡 流式支持 - 实时流式传输完成、聊天和微调事件
• 🛠️ 开发者友好 - 全面的错误处理和日志记录
• 📚 丰富的示例 - 为每个实现的功能提供即用型示例
• 🎨 现代 UI 支持 - 针对 Flutter 应用程序进行了优化
• 🔄 自定义 API - 额外的自定义端点以增强功能

---

🚀 快速入门

安装

将该包添加到你的 pubspec.yaml 文件中：

dependencies:
  dart_openai: 

基本设置

import 'package:dart_openai/dart_openai.dart';

void main() {
  // 设置你的 API 密钥
  OpenAI.apiKey = "your-api-key-here";
  
  // 可选：设置组织 ID
  OpenAI.organization = "your-org-id";
  
  // 可选：配置超时时间
  OpenAI.requestsTimeOut = Duration(seconds: 60);
  
  // 可选：启用日志记录
  OpenAI.showLogs = true;
  
  runApp(MyApp());
}

第一个 API 调用

// 简单的聊天完成
final chatCompletion = await OpenAI.instance.chat.create(
  model: "gpt-3.5-turbo",
  messages: [
    OpenAIChatCompletionChoiceMessageModel(
      role: OpenAIChatMessageRole.user,
      content: "你好，最近怎么样？",
    ),
  ],
);

print(chatCompletion.choices.first.message.content);

---

📊 API 覆盖范围（2025年）

API 功能	状态	详情	最后更新
📋 响应	✅ 完整	全部	11-08-2025 17:33:39
💭 对话	✅ 完整	全部	11-08-2025 17:38:56
🎵 音频	✅ 完整	全部	11-08-2025 17:42:54
🎬 视频	🗓️ 计划中	-
🎨 图像	✅ 完整	全部	11-08-2025 17:53:45
🎨 图像流式传输	🗓️ 计划中	-
📊 嵌入	✅ 完整	全部	11-08-2025 17:56:30
⚖️ 评估	✅ 完整	全部	11-08-2025 21:04:36
🔧 微调	🧩 完成 70%	缺少较新的端点
📊 评分器	✅ 完整	全部	11-08-2025 21:46:48
📦 批处理	🗓️ 计划中	-
📁 文件	✅ 完整	全部	11-08-2025 21:51:34
📤 上传	🗓️ 计划中	-
🤖 模型	✅ 完整	全部	11-08-2025 21:53:13
🛡️ 内容审核	✅ 完整	全部	11-08-2025 21:54:01
🗃️ 向量存储	✅ 完整	全部	11-19-2025 12:24:15
💬 ChatKit	❌ 未计划	测试版功能
📦 容器	✅ 完整	全部	11-19-2025 12:24:15
🕛 实时	🗓️ 计划中	-
💬 聊天完成	✅ 完整	不包括流式功能
🤖 助手	❌ 未计划	测试版功能
🤖 管理	🗓️ 计划中	-
📝 完成（旧版）	✅ 完整	全部
✏️ 编辑（旧版）	✅ 完整	全部

---

📚 文档

核心 API

📋 响应

// 创建响应
OpenAiResponse response = await OpenAI.instance.responses.create(
  input: "Your input text here",  
  model: "gpt-4",
);

// 获取响应
OpenAiResponse response = await OpenAI.instance.responses.get(
  responseId: "response-id-here",
  startingAfter: 0, 
);

// 删除响应
await OpenAI.instance.responses.delete(
  responseId: "response-id-here",
);

// 取消响应
OpenAiResponse response = await OpenAI.instance.responses.cancel(
  responseId: "response-id-here",
);

// 列出输入项
OpenAiResponseInputItemsList response = await OpenAI.instance.responses.listInputItems(
  responseId: "response-id-here",
  limit: 10, 
);


// 获取输入 token 数量
int inputTokens = await OpenAI.instance.responses.getInputTokenCounts(
  model: "gpt-5",
  input: "Your input text here",
);

💭 对话

// 创建对话
OpenAIConversation conversation = await OpenAI.instance.conversations.create(
  items: [{
    "type": "message",
    "role": "user",
    "content": "你好！",
  }],
  metadata: {
    "key": "value",
    "another_key": "another_value",
  },
);


// 获取对话
OpenAIConversation conversation = await OpenAI.instance.conversations.get(
  conversationId: "conversation-id-here",
);

// 更新对话
OpenAIConversation updatedConversation = await OpenAI.instance.conversations.update(
  conversationId: "conversation-id",
  metadata: {
    "key": "new_value",
  },
);

// 删除对话
 await OpenAI.instance.conversations.delete(
  conversationId: "conversation-id-here",
);

// 列出项目
OpenAIConversationItemsResponse itemsList = await OpenAI.instance.conversations.listItems(
  conversationId: "conversation-id-here",
  limit: 10, 
);

// 创建条目
OpenAIConversationItem item = await OpenAI.instance.conversations.createItems(
  conversationId: "conversation-id-here",
  items: [
    // ...
  ],
);

// 获取条目
OpenAIConversationItem item = await OpenAI.instance.conversations.getItem(
  conversationId: "conversation-id-here",
  itemId: "item-id-here",
);

// 删除条目
await OpenAI.instance.conversations.deleteItem(
  conversationId: "conversation-id-here",
  itemId: "item-id-here",
);

🎵 音频

// 创建语音
File speechFile = await OpenAI.instance.audio.createSpeech(
  model: "tts-1",
  input: "要转换为语音的文本",
  voice: OpenAIAudioVoice.fable,
  responseFormat: OpenAIAudioSpeechResponseFormat.mp3,
  outputDirectory: "/path/to/output/directory",
  outputFileName: "output_speech.mp3",
);


// 转录音频
OpenAITranscriptionGeneralModel transcription = await OpenAI.instance.audio.createTranscription(
  model: "whisper-1",
  file: File("path/to/audio.mp3"),
  include: ["logprobs"],
  responseFormat: OpenAIAudioResponseFormat.verbose_json,
  language: "en",
  prompt: "这是一个用于指导转录的示例提示",
);
// 处理不同的转录响应格式
if (transcription is OpenAITranscriptionModel) {
  print(transcription.logprobs);
  print(transcription.text);
  print(transcription.usage);
} else if (transcription is OpenAITranscriptionVerboseModel) {
  // 打印转录内容。
  print(transcription.text);
  print(transcription.segments?.map((e) => e.end));
}

// 创建翻译
final translationText = await OpenAI.instance.audio.createTranslation(
  file: File("path/to/audio.mp3"),
  model: "whisper-1",
  prompt: "使用不常见的英语单词",
  responseFormat: OpenAIAudioResponseFormat.json,
);

🎬 视频

// （待实现）

🎨 图像

// 生成图像
OpenAIImageModel image = await OpenAI.instance.image.create(
  model: "dall-e-3",
  prompt: "太空飞船中的猫的图像",
  responseFormat: OpenAIImageResponseFormat.url,
  size: OpenAIImageSize.size1024,
  quality: OpenAIImageQuality.standard,
  style: OpenAIImageStyle.vivid,
);

// 编辑图像
OpenAIImageModel imageEdit = await OpenAI.instance.image.edit(
  prompt: '一座有山和河流的奇幻景观',
  image: File("path/to/image.png"),
  size: OpenAIImageSize.size1024,
  responseFormat: OpenAIImageResponseFormat.b64Json,
);

// 创建变体
List<OpenAIImageModel> imageVariation = await OpenAI.instance.image.variation(
  model: "dall-e-2",
  image: File("path/to/image.png"),
  size: OpenAIImageSize.size512,
  responseFormat: OpenAIImageResponseFormat.url,
);

🎨 图像流

// （待实现）

📊 嵌入

OpenAIEmbeddingsModel embedding = await OpenAI.instance.embedding.create(
  model: "text-embedding-ada-002",
  input: "这是一段示例文本",
);

⚖️ 评估

// 创建评估
OpenAIEval eval = await OpenAI.instance.evals.create(
  dataSourceConfig: RequestDatatSourceConfig.logs(),
);

// 获取评估
OpenAIEval eval = await OpenAI.instance.evals.get(
  evalId: "eval-id-here",
);

// 更新评估
OpenAIEval updatedEval = await OpenAI.instance.evals.update(
  evalId: "eval-id-here",
  metadata: {
    "key": "new_value",
  },
);

// 删除评估
 await OpenAI.instance.evals.delete(
  evalId: "eval-id-here",
);

// 列出评估
OpenAIEvalsList evalsList = await OpenAI.instance.evals.list(
  limit: 10, 
);

// 获取评估运行。
OpenAIEvalRunsList evalRuns = await OpenAI.instance.evals.getRuns(
  evalId: "eval-id-here",
  limit: 3, 
);

// 获取评估运行
OpenAIEvalRun evalRun = await OpenAI.instance.evals.getRun(
  evalId: "eval-id-here",
  runId: "run-id-here",
);

// 创建运行
OpenAIEvalRun createdRun = await OpenAI.instance.evals.createRun(
  evalId: "eval-id-here",
  dataSource: EvalRunDataSource.jsonl(),
);

// 取消运行
OpenAIEvalRun canceledRun = await OpenAI.instance.evals.cancel(
  evalId: "eval-id-here",
  runId: "run-id-here",
);

// 删除运行
 await OpenAI.instance.evals.deleteRun(
  evalId: "eval-id-here",
  runId: "run-id-here",
);

// 获取评估运行的输出项。
OpenAIEvalRunOutputItem outputItem = await OpenAI.instance.evals.getEvalRunOutputItem(
  evalId: "eval-id-here",
  runId: "run-id-here",
  outputItemIdn: "item-id-here",
);

// 获取评估运行的输出项。
OpenAIEvalRunOutputItemsList outputItems = await OpenAI.instance.evals.getEvalRunOutputItems(
  evalId: "eval-id-here",
  runId: "run-id-here",
  limit: 10,
);

🔧 微调

// （待实现）

📊 评分器

// 评分器
final grader = OpenAIGraders.stringCheckGrader(...);
final grader2 = OpenAIGraders.textSimilarityGrader(...);
final grader3 = OpenAIGraders.scoreModelGrader(...);
final grader4 = OpenAIGraders.labelModelGrader(...);
final grader5 = OpenAIGraders.pythonGrader(...);
final grader6 = OpenAIGraders.multiGrader(...);

// 运行评分器
final grader = await OpenAI.instance.graders.runGrader(
 grader: grader,
 modelSample: "待评分的模型输出", 
);

// 验证评分器
final isValid = OpenAI.instance.graders.validateGrader(
  grader: grader
);

📦 批处理

// （待实现）

📁 文件

// 上传文件
OpenAIFileModel file = await OpenAI.instance.files.upload(
  file: File("path/to/file.jsonl"),
  purpose: "assistants",
);

// 列出文件
List<OpenAIFileModel> files = await OpenAI.instance.files.list(
  limit: 10,
);

// 检索文件
OpenAIFileModel file = await OpenAI.instance.files.retrieve(
   "file_id" 
);

// 删除文件
await OpenAI.instance.files.delete("file-id-here");

// 检索文件内容
final content = await OpenAI.instance.files.retrieveContent(
  "file_id"
);

📤 上传

// （待实现）

🤖 模型

// 列出所有可用的模型
List<OpenAIModelModel> models = await OpenAI.instance.model.list();

// 检索特定模型
OpenAIModelModel model = await OpenAI.instance.model.retrieve("gpt-3.5-turbo");

// 删除微调后的模型
bool deleted = await OpenAI.instance.model.delete("fine-tuned-model-id");

🛡️ 内容审核

OpenAIModerationModel moderation = await OpenAI.instance.moderation.create(
  input: ["需要进行内容审核的文本"],
  model: "omni-moderation-latest",
);

🗃️ 向量存储

向量存储

// 创建向量存储
  OpenAIVectorStoreModel vectorStore = await OpenAI.instance.vectorStores.vectorStores.create(
    name: "example_vector_store",
    chunkingStrategy: OpenAIVectorStoreChunkingStrategy.static(
      chunkOverlapTokens: 300,
      maxChunkSizeTokens: 750,
    ),
    expiresAfter: OpenAIVectorStoreExpiresAfter(
      anchor: "last_active_at",
      days: 1,
    ),
  ); 

  // 列出向量存储
 OpenAIVectorStoreListModel allVEctorStores = await OpenAI.instance.vectorStores.vectorStores.list(limit: 30);

 // 获取向量存储
 final firstVectorStoreAsync = await OpenAI.instance.vectorStores.vectorStores.get(
   vectorStoreId: "vector_store_id",
 );

// 修改向量存储
final updatedVectorStore = await OpenAI.instance.vectorStores.vectorStores.modify(
  vectorStoreId: "vector_store_id",
  name: "updated_vector_store_name",
);

// 删除向量存储
await OpenAI.instance.vectorStores.vectorStores.delete(
  vectorStoreId: "vector_store_id",
);

// 在向量存储中搜索
final searchVEctorStoreResult = await OpenAI.instance.vectorStores.vectorStores.search(
   vectorStoreId: updatedVectorStore.id,
   query: "example",
   maxNumResults: 10,
   filters: OpenAIVectorStoresSearchFilter.comparison(
     type: "eq",
     key: "metadata.example_key",
     value: "example_value",
   ),
   rankingOptions: OpenAIVectorStoresRankingOptions(
     ranker: "none",
     scoreThreshold: 0,
   ),
);

向量存储文件

// 创建向量存储文件
final createdVectorStoreFile = await OpenAI.instance.vectorStores.vectorStoresFiles.create(
  vectorStoreId: "vector_store_id",
  fileId: "file_id",
  attributes: {
    "chapter": "Chapter 1",
  },
  chunckingStrategy: OpenAIVectorStoreChunkingStrategy.static(
    chunkOverlapTokens: 300,
    maxChunkSizeTokens: 750,
  ),
);

// 列出向量存储文件
final vectorStoreFiles = await OpenAI.instance.vectorStores.vectorStoresFiles.list(
  vectoreStoreId: "vector_store_id",
  limit: 60,
);

// 获取向量存储文件
final vectorStoreFile = await OpenAI.instance.vectorStores.vectorStoresFiles.get(
  fileId: "file_id",
  vectorStoreId: "vector_store_id",
);

// 获取向量存储文件内容
final vectorStoreFileContent = await OpenAI.instance.vectorStores.vectorStoresFiles.getContent(
  fileId: "file_id",
  vectorStoreId: "vector_store_id",
);

// 更新向量存储文件
final updatedVectorStoreFile = await OpenAI.instance.vectorStores.vectorStoresFiles.update(
  fileId: "file_id",
  vectorStoreId: "vector_store_id",
  attributes: {
    "chapter": "Updated Chapter 1",
  },
);

// 删除向量存储文件
await OpenAI.instance.vectorStores.vectorStoresFiles.delete(
  fileId: "file_id",
  vectorStoreId: "vector_store_id",
);

向量存储文件批次

// 创建向量存储文件批次
final vectoreStoreFileBatch = await OpenAI.instance.vectorStores.vectorStoreFileBatch.create(
  vectorStoreId: "vector_store_id",
  chunkingStrategy: OpenAIVectorStoreChunkingStrategy.static(
    chunkOverlapTokens: 200,
    maxChunkSizeTokens: 550,
  ),
  attributes: {
    "batch_name": "My First Batch",
  },
  fileIds: ["file-abc123", "file-def456"],
);

// 获取向量存储文件批次
final batch = await OpenAI.instance.vectorStores.vectorStoreFileBatch.get(
  batchId: "batch_id",
  vectorStoreId: "vector_store_id",
);

// 取消向量存储文件批次
final cancelledBatch = await OpenAI.instance.vectorStores.vectorStoreFileBatch.cancel(
  batchId: "batch_id",
  vectorStoreId: "vector_store_id",
);

// 列出批次中的向量存储文件
final vectorStoreBatchFiles = await OpenAI.instance.vectorStores.vectorStoreFileBatch.list(
  vectorStoreId: "vector_store_id",
  batchId: 'batch_id',
);

📦 容器

容器

// 创建容器
final container = await OpenAI.instance.container.containers.create(
  name: "my special container",
);

// 列出容器
final containers = await OpenAI.instance.container.containers.list(
  limit: 20,
);

// 获取容器
final firstContainer = await OpenAI.instance.container.containers.get(
  containerId: "container_id",
);

// 删除容器
await OpenAI.instance.container.containers.delete(
  containerId: "container_id",
);

容器文件

// 创建容器文件
final containerFile = await OpenAI.instance.container.containerFiles.create(
  file: File("path/to/file"),
  containerId: "container_id",
);

// 获取容器文件
final gotContainerFile = await OpenAI.instance.container.containerFiles.get(
  containerId: "container_id",
  fileId: "file_id",
);

// 获取容器文件内容
final gotContainerFileContent =
    await OpenAI.instance.container.containerFiles.getContent(
  containerId: "container_id",
  fileId: "file_id",
);

// 列出容器文件
final allContainerFiles = await OpenAI.instance.container.containerFiles.list(
  containerId: "container_id",
  limit: 20,
);

// 删除容器文件
await OpenAI.instance.container.containerFiles.delete(
  fileId: "file_id",
  containerId: "container_id",
);

🕛 实时

// (待实现)

💬 聊天补全

// 基本的聊天补全
OpenAIChatCompletionModel chat = await OpenAI.instance.chat.create(
  model: "gpt-3.5-turbo",
  messages: [
    OpenAIChatCompletionChoiceMessageModel(
      role: OpenAIChatMessageRole.user,
      content: "Hello, how can you help me?",
    ),
  ],
  temperature: 0.7,
  maxTokens: 150,
);

// 流式聊天补全
Stream<OpenAIStreamChatCompletionModel> chatStream = OpenAI.instance.chat.createStream(
  model: "gpt-3.5-turbo",
  messages: [
    OpenAIChatCompletionChoiceMessageModel(
      role: OpenAIChatMessageRole.user,
      content: "Tell me a story",
    ),
  ],
);

chatStream.listen((event) {
  print(event.choices.first.delta.content);
});

🤖 管理

// (待实现)

---

🔧 配置

环境变量

// 使用 envied 包
@Envied(path: ".env")
abstract class Env {
  @EnviedField(varName: 'OPEN_AI_API_KEY')
  static const apiKey = _Env.apiKey;
}

void main() {
  OpenAI.apiKey = Env.apiKey;
  runApp(MyApp());
}

自定义配置

void main() {
  // 设置 API 密钥
  OpenAI.apiKey = "your-api-key";
  
  // 设置组织 ID（可选）
  OpenAI.organization = "your-org-id";
  
  // 设置自定义基础 URL（可选）
  OpenAI.baseUrl = "https://api.openai.com/v1";
  
  // 设置请求超时时间（可选）
  OpenAI.requestsTimeOut = Duration(seconds: 60);
  
  // 启用日志记录（可选）
  OpenAI.showLogs = true;
  OpenAI.showResponsesLogs = true;
  
  runApp(MyApp());
}

---

🚨 错误处理

try {
  final chat = await OpenAI.instance.chat.create(
    model: "gpt-3.5-turbo",
    messages: [
      OpenAIChatCompletionChoiceMessageModel(
        role: OpenAIChatMessageRole.user,
        content: "Hello",
      ),
    ],
  );
} on RequestFailedException catch (e) {
  print("请求失败: ${e.message}");
  print("状态码: ${e.statusCode}");
} on MissingApiKeyException catch (e) {
  print("未设置 API 密钥: ${e.message}");
} on UnexpectedException catch (e) {
  print("意外错误: ${e.message}");
}

---

🤝 贡献

我们欢迎贡献！以下是您可以帮助的方式：

🐛 错误报告

• 使用 GitHub Issues 报告错误
• 包括复现步骤和环境详情

💡 功能请求

• 通过 GitHub Issues 提出新功能建议
• 在创建新问题之前，请先检查现有问题

🔧 代码贡献

• 分叉仓库
• 创建特性分支
• 进行更改
• 如果适用，添加测试
• 提交拉取请求

📚 文档

• 帮助改进文档
• 为缺失的功能添加示例
• 修复拼写错误并提高清晰度

💰 赞助

• 赞助该项目
• 帮助维护和改进这个包

---

📜 许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。

---

🙏 致谢

• 感谢 OpenAI 提供的优秀 AI 模型和 API
• 感谢帮助维护和改进本包的 贡献者
• 感谢在经济上支持本项目的 赞助者
• 感谢提供反馈和建议的 社区

---

📞 支持

• 📖 完整文档
• 🐛 报告问题
• 💬 讨论区
• 📧 联系

---

Dart OpenAI 快速上手指南

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Windows、macOS 或 Linux
• 运行时环境：已安装 Dart SDK (推荐最新稳定版) 或 Flutter SDK
• 依赖项：有效的 OpenAI API Key
• 网络环境：能够访问 pub.dev 和 OpenAI API 服务（国内开发者如遇网络问题，建议配置代理或使用国内镜像源）

注意：本库为社区维护的非官方客户端，OpenAI 官方暂未发布 Dart 版本 SDK。

安装步骤

1. 添加依赖

打开项目的 pubspec.yaml 文件，在 dependencies 部分添加 dart_openai：

dependencies:
  dart_openai: ^latest_version

注：请将 ^latest_version 替换为 pub.dev 上的最新版本号，或直接运行下方命令自动获取最新版。

2. 获取依赖包

在项目根目录下执行以下命令安装依赖：

dart pub get

如果是 Flutter 项目：

flutter pub get

国内加速提示：如果下载速度较慢，可临时使用清华大学或上海交大镜像源：

export PUB_HOSTED_URL=https://mirrors.tuna.tsinghua.edu.cn/dart-pub
flutter pub get

基本使用

1. 初始化配置

在应用启动时（如 main.dart），设置您的 API Key 及可选配置：

import 'package:dart_openai/dart_openai.dart';

void main() {
  // 必填：设置 OpenAI API Key
  OpenAI.apiKey = "your-api-key-here";
  
  // 可选：设置组织 ID (如有)
  OpenAI.organization = "your-org-id";
  
  // 可选：配置请求超时时间
  OpenAI.requestsTimeOut = Duration(seconds: 60);
  
  // 可选：开启日志调试
  OpenAI.showLogs = true;
  
  runApp(MyApp());
}

2. 发起第一个对话请求

使用 GPT 模型进行简单的聊天补全：

// 创建聊天完成请求
final chatCompletion = await OpenAI.instance.chat.create(
  model: "gpt-3.5-turbo",
  messages: [
    OpenAIChatCompletionChoiceMessageModel(
      role: OpenAIChatMessageRole.user,
      content: "Hello, how are you?",
    ),
  ],
);

// 输出回复内容
print(chatCompletion.choices.first.message.content);

3. 其他核心功能示例

本库支持丰富的 OpenAI 接口，以下是常用功能的简要调用方式：

生成图片 (DALL-E 3):

OpenAIImageModel image = await OpenAI.instance.image.create(
  model: "dall-e-3",
  prompt: "image of a cat in a spaceship",
  size: OpenAIImageSize.size1024,
);

语音转文字 (Whisper):

OpenAITranscriptionGeneralModel transcription = await OpenAI.instance.audio.createTranscription(
  model: "whisper-1",
  file: File("path/to/audio.mp3"),
  responseFormat: OpenAIAudioResponseFormat.json,
);
print(transcription.text);

文本嵌入 (Embeddings):

OpenAIEmbeddingsModel embedding = await OpenAI.instance.embedding.create(
  model: "text-embedding-ada-002",
  input: "This is a sample text",
);

更多高级用法（如流式传输、微调、评估等）请参考官方文档或仓库中的 Examples 章节。