OpenAI | ArcBlock

@aigne/openai 套件提供了與 OpenAI 模型套件的無縫整合，讓開發者可以直接在 AIGNE 框架內利用 GPT 等服務進行聊天完成、DALL-E 進行圖片生成，以及 Sora 進行影片創作。本文件提供了安裝、設定和使用這些模型的全面指南。

關於可用模型供應商的更廣泛概述，請參閱模型部分。

功能

OpenAI 整合的設計旨在穩健且對開發者友善，提供一系列功能：

全面的模型支援：完全整合 OpenAI 的聊天、圖片和影片生成 API。
官方 SDK：建立在官方 OpenAI SDK 之上，以獲得最高的可靠性和相容性。
進階功能：包含支援函式呼叫、串流回應和結構化 JSON 輸出。
型別安全：為所有模型設定和 API 回應提供完整的 TypeScript 型別，確保程式碼品質和自動完成功能。
一致的介面：遵循 AIGNE 框架的模型介面，以在不同供應商之間實現統一的實作。
廣泛的設定：提供詳細的選項來微調模型行為，以滿足特定的應用需求。

安裝

要將 OpenAI 模型整合到您的專案中，請將 @aigne/openai 套件與 @aigne/core 框架一起安裝。請使用適合您套件管理工具的指令：

npm

npm install @aigne/openai @aigne/core

yarn

yarn add @aigne/openai @aigne/core

pnpm

pnpm add @aigne/openai @aigne/core

聊天模型 (OpenAIChatModel)

OpenAIChatModel 類別是與 OpenAI 的文字型語言模型（如 GPT-4o 和 GPT-4o-mini）互動的主要介面。

設定

在建立 OpenAIChatModel 的實例時，您必須提供您的 OpenAI API 金鑰。這可以直接在建構函式中傳遞，或設定為名為 OPENAI_API_KEY 的環境變數。

apiKey string — 您的 OpenAI API 金鑰。若省略，系統將會尋找 OPENAI_API_KEY 環境變數。
baseURL string — OpenAI API 的選用基礎 URL，可用於透過代理伺服器或替代端點進行連線。
model string (default: gpt-4o-mini) — 用於聊天完成的模型識別碼（例如 "gpt-4o"）。
modelOptions object — 一組用於控制生成過程的參數。
- temperature number — 控制輸出的隨機性。較低的值會產生更具確定性的結果。
- topP number — 溫度取樣的替代方案，稱為核心取樣 (nucleus sampling)。
- frequencyPenalty number — 降低重複詞元 (token) 的可能性。
- presencePenalty number — 降低重複主題的可能性。
- parallelToolCalls boolean (default: true) — 使模型能夠同時執行多個函式呼叫。
- reasoningEffort string | number — 對於推理模型 (o1/o3)，設定推理的努力程度（'minimal'、'low'、'medium'、'high' 或一個詞元數量）。
clientOptions object — 直接傳遞給底層 OpenAI SDK 客戶端的額外選項，用於進階自訂。

基本用法

以下範例展示如何實例化 OpenAIChatModel 並使用 invoke 方法來取得回應。

基本聊天完成

import { OpenAIChatModel } from "@aigne/openai";

const model = new OpenAIChatModel({
  // 建議使用環境變數來設定 API 金鑰。
  apiKey: "your-api-key",
  model: "gpt-4o",
  modelOptions: {
    temperature: 0.7,
  },
});

const result = await model.invoke({
  messages: [{ role: "user", content: "Hello, who are you?" }],
});

console.log(result);

範例回應

{
  "text": "Hello! How can I assist you today?",
  "model": "gpt-4o",
  "usage": {
    "inputTokens": 10,
    "outputTokens": 9
  }
}

串流回應

對於即時應用程式，您可以透過將 { streaming: true } 傳遞給 invoke 方法來啟用串流。這會回傳一個非同步迭代器，它會在回應區塊生成時逐一產出。

串流聊天回應

import { isAgentResponseDelta } from "@aigne/core";
import { OpenAIChatModel } from "@aigne/openai";

const model = new OpenAIChatModel({
  apiKey: "your-api-key",
  model: "gpt-4o",
});

const stream = await model.invoke(
  {
    messages: [{ role: "user", content: "Hello, who are you?" }],
  },
  { streaming: true },
);

let fullText = "";
for await (const chunk of stream) {
  if (isAgentResponseDelta(chunk)) {
    const text = chunk.delta.text?.text;
    if (text) {
      fullText += text;
      process.stdout.write(text);
    }
  }
}

console.log("\n--- Response Complete ---");

圖片模型 (OpenAIImageModel)

OpenAIImageModel 類別提供了與 OpenAI 圖片生成和編輯模型（如 DALL-E 2、DALL-E 3 和 gpt-image-1）互動的介面。

設定

圖片模型的設定與聊天模型相似，需要一個 API 金鑰，並允許設定模型特定的選項。

apiKey string — 您的 OpenAI API 金鑰。若未提供，則預設使用 OPENAI_API_KEY 環境變數。
baseURL string — OpenAI API 的選用基礎 URL。
model string (default: dall-e-2) — 要使用的圖片模型（例如 "dall-e-3", "gpt-image-1"）。
modelOptions object — 控制圖片生成過程的參數。可用選項因模型而異。
- size string — 生成圖片的尺寸（例如 '1024x1024'）。
- quality string — 圖片品質，可為 'standard' 或 'hd'（僅限 DALL-E 3）。
- style string — 藝術風格，可為 'vivid' 或 'natural'（僅限 DALL-E 3）。
- n number — 要生成的圖片數量。
clientOptions object — 直接傳遞給底層 OpenAI SDK 客戶端的進階選項。

圖片生成

若要生成圖片，請建立一個 OpenAIImageModel 的實例，並用文字提示來呼叫它。

圖片生成

import { OpenAIImageModel } from "@aigne/openai";

const imageModel = new OpenAIImageModel({
  apiKey: "your-api-key",
  model: "dall-e-3",
  modelOptions: {
    size: "1024x1024",
    quality: "standard",
    style: "vivid",
  },
});

const result = await imageModel.invoke({
  prompt: "A futuristic city at sunset with flying cars",
});

console.log(result);

範例回應

{
  "images": [
    {
      "type": "url",
      "url": "https://...",
      "mimeType": "image/png"
    }
  ],
  "usage": {
    "inputTokens": 0,
    "outputTokens": 0
  },
  "model": "dall-e-3"
}

圖片編輯

圖片編輯功能由特定模型（如 gpt-image-1）支援。若要編輯圖片，請同時提供提示和參考圖片。

圖片編輯

import { OpenAIImageModel } from "@aigne/openai";

const imageModel = new OpenAIImageModel({
  apiKey: "your-api-key",
  model: "gpt-image-1",
});

const result = await imageModel.invoke({
  prompt: "Add a rainbow to the sky",
  image: [
    {
      type: "url",
      url: "https://example.com/original-image.png",
    },
  ],
});

console.log(result.images); // 編輯後的圖片陣列

影片模型 (OpenAIVideoModel)

OpenAIVideoModel 類別能夠使用 OpenAI 的 Sora 模型生成影片。

設定

影片模型需要一個 API 金鑰，並允許指定模型、解析度和時長。

apiKey string — 您的 OpenAI API 金鑰。若未提供，則預設使用 OPENAI_API_KEY 環境變數。
model string (default: sora-2) — 要使用的影片模型，可以是 "sora-2"（標準）或 "sora-2-pro"（更高品質）。
modelOptions object — 控制影片生成過程的參數。
- size string (default: 1280x720) — 影片解析度（例如 '1280x720' 為橫向，'720x1280' 為縱向）。
- seconds string (default: 4) — 影片時長（秒）。可接受的值為 '4'、'8' 或 '12'。

影片生成

以下範例示範如何從文字提示生成短片。

影片生成

import { OpenAIVideoModel } from "@aigne/openai";

const videoModel = new OpenAIVideoModel({
  apiKey: "your-api-key",
  model: "sora-2",
  modelOptions: {
    size: "1280x720",
    seconds: "4",
  },
});

const result = await videoModel.invoke({
  prompt: "A serene lake with mountains in the background, gentle waves rippling",
});

console.log(result);

範例回應

{
  "videos": [
    {
      "type": "file",
      "data": "base64-encoded-video-data...",
      "mimeType": "video/mp4",
      "filename": "video-id.mp4"
    }
  ],
  "usage": {
    "inputTokens": 0,
    "outputTokens": 0
  },
  "model": "sora-2",
  "seconds": 4
}

圖片轉影片生成

您也可以透過將靜態圖片動畫化來生成影片。

圖片轉影片

import { OpenAIVideoModel } from "@aigne/openai";

const videoModel = new OpenAIVideoModel({
  apiKey: "your-api-key",
  model: "sora-2",
});

const result = await videoModel.invoke({
  prompt: "Animate this image with gentle movement",
  image: {
    type: "url",
    url: "https://example.com/input-image.png",
  },
  size: "1280x720",
  seconds: "8",
});

console.log(result.videos);

總結

本指南已涵蓋將 OpenAI 的聊天、圖片和影片模型整合到您的 AIGNE 應用程式中的基本要素。透過使用 @aigne/openai 套件，您可以輕鬆地利用這些進階 AI 功能的強大威力。

如需更多詳細資訊，請參閱官方 OpenAI API 文件。若要探索其他支援的模型供應商，請造訪模型總覽。