AI SDK

提供統一的 AI 模型配置中心，支援各大主流 AI 模型，一次配置處處可用，無需重複設定 API Key。

注意：此功能需要在 Eagle 4.0 Build20 以上版本才能使用（目前尚未發佈，詳細發佈時間請關注 Eagle 官網）

---

AI SDK 相依插件簡介

「AI SDK 相依插件」是一款面向插件開發者的開發工具包，提供統一的 AI 模型配置中心，支援各大主流 AI 模型，一次配置，處處可用。透過整合 AI SDK，開發者可在自身的插件中輕鬆實現文字生成、結構化物件生成以及串流處理等 AI 功能。

統一配置中心：一次設定，處處可用

AI SDK 插件支援以下 8 個 Provider：

商業模型：

• OpenAI（GPT-5.2、GPT-5、o3 等）

• Anthropic Claude（Claude Sonnet 4.6、Claude Opus 4.6 等）

• Google Gemini（Gemini 3 Pro、Gemini 3 Flash 等）

• DeepSeek（DeepSeek V3、DeepSeek R1 等）

• 通義千問（Qwen3 系列）

本地模型（完全離線執行）：

• Ollama（支援 Llama 4、Qwen3、Gemma 3 等）

• LM Studio（圖形化介面，新手友善）

OpenAI 相容協議：

• OpenAI Compatible — 支援任何相容 OpenAI API 協議的服務端點（如 Groq、Together AI、Fireworks、vLLM 等），只需提供 Base URL 即可連接，API Key 為選填。

後續版本將陸續增加更多主流模型服務提供商的支援。

配置一次後，所有 AI 相關插件都能直接使用，無需重複設定。例如：你安裝了「AI 翻譯」與「AI 重新命名」插件，它們都會自動共用你在 AI SDK 裡填好的配置，甚至可以各自選擇不同的模型，而不需要再次輸入 API Key。

開放的開發環境

基於 ai-sdk.dev 標準（AI SDK v6），AI SDK 插件為開發者提供了一組乾淨、穩定的基礎設施。開發者不用再花心力處理 API Key 儲存、模型切換、錯誤處理等基礎配置，可以專注於插件的功能創新。唯一的區別在於 Provider 的取得方式——我們使用自行開發的 Provider 來確保更好的穩定性和使用者體驗。

版本說明：此插件基於 AI SDK v6 建構，與 ai-sdk.dev 官方文件保持同步。

---

安裝與設定

安裝步驟

1. 進入 Eagle 插件中心

2. 搜尋並找到「AI SDK」插件

3. 點擊安裝

4. 安裝完成後，打開 偏好設置，在左側欄找到「AI 模型套件」

5. 在右側設置區塊中配置模型服務提供商，並設定預設模型（語言模型、視覺模型）

當使用者安裝具有 AI SDK 相依的插件時，Eagle 會自動提示使用者安裝「AI SDK 相依插件」。因此，開發者無需專門編寫程式碼讓使用者進行安裝，系統會自動確保相關相依已安裝後才允許插件執行。

在 manifest.json 中宣告相依

在插件的 manifest.json 中加入 dependencies 欄位：

{
    "id": "YOUR_PLUGIN_ID",
    "version": "1.0.0",
    "platform": "all",
    "arch": "all",
    "name": "我的 AI 插件",
    "logo": "/logo.png",
    "keywords": [],
    "dependencies": ["ai-sdk"],
    "devTools": false,
    "main": {
        "url": "index.html",
        "width": 640,
        "height": 480
    }
}

關鍵設定為 "dependencies": ["ai-sdk"]，這會讓 Eagle 知道此插件需要 AI SDK 才能運作。

---

快速開始

取得 AI SDK 模組：

const ai = eagle.extraModule.ai;

推薦做法：使用預設模型

使用者通常會在偏好設置的「AI 模型套件」中，事先選好偏好的語言模型與視覺模型。透過 getDefaultModel() 直接繼承使用者的選擇，是最簡單也最推薦的做法：

eagle.onPluginCreate(async (plugin) => {
    const ai = eagle.extraModule.ai;
    const { generateText } = ai;

    // 取得使用者設定的預設語言模型（同步，無需 await）
    // 另有 getDefaultModel("image") 可取得使用者的預設視覺模型
    const defaultLLM = ai.getDefaultModel("chat");

    if (!defaultLLM) {
        console.log("請先在 AI SDK 設定中選擇預設語言模型");
        ai.open(); // 自動開啟偏好設置中的模型設定面板
        return;
    }

    // 直接用 provider::model 字串取得模型
    const model = ai.getModel(defaultLLM);

    // 生成文字
    const result = await generateText({
        model,
        prompt: "請用一句話介紹數位藝術",
    });

    console.log(result.text);
});

🦄 最佳實踐： 優先使用 getDefaultModel("chat") 取得使用者的偏好模型，而非在程式碼中寫死特定的 Provider 與模型名稱。這樣做有兩大好處：

1. 開發更輕鬆——不需要自己實作模型選擇器，直接繼承使用者在 AI SDK 中的偏好設定。

2. 避免配置問題——如果你在程式碼中指定 openai("gpt-5")，但使用者沒有配置 OpenAI，就會出錯。使用預設模型則能保證使用者已經配置並驗證過。

指定特定 Provider

如果你的插件確實需要使用特定的 Provider（例如只有 OpenAI 支援的功能），也可以直接指定：

eagle.onPluginCreate(async (plugin) => {
    const ai = eagle.extraModule.ai;
    const { generateText } = ai;

    // 取得特定 Provider（同步，無需 await）
    const openai = ai.getProvider("openai");

    const result = await generateText({
        model: openai("gpt-5"),
        prompt: "請用一句話介紹數位藝術",
    });

    console.log(result.text);
});

---

核心概念

Provider 與 Model 的關係

AI SDK 採用雙層結構：Provider（提供者）負責管理 API 連線與認證，Model（模型）則是實際執行 AI 任務的單位。

Provider（如 openai）
  └── Model（如 gpt-5）
  └── Model（如 gpt-5.2）

provider::model 格式

重要： Provider 與 Model 之間使用雙冒號 :: 分隔，而非單冒號或斜線。

// ✅ 正確
"openai::gpt-5"
"anthropic::claude-sonnet-4-6-20250514"
"google::gemini-3-flash"

// ❌ 錯誤
"openai/gpt-5"
"openai:gpt-5"

此格式用於 getModel() 和 getDefaultModel() 等方法。

同步 vs 非同步方法

AI SDK 中的方法明確區分為同步與非同步兩類：

同步方法（無需 await）：

• getProviders()、getProvider()、getAvailableProviders()、getModel()

• getDefaultModel()

非同步方法（需要 await）：

• generateText()、generateObject()、streamText()、streamObject()

• Provider 實例的 verify()、getModels()、hasModel()

取得 Model 的三種方式

const ai = eagle.extraModule.ai;

// ⭐ 推薦：使用預設模型，直接繼承使用者偏好
const defaultLLM = ai.getModel(ai.getDefaultModel("chat"));   // 預設語言模型
const defaultVLM = ai.getModel(ai.getDefaultModel("image"));  // 預設視覺模型

// 方式二：直接用 provider::model 格式取得
const model = ai.getModel("openai::gpt-5");

// 方式三：先取得 Provider，再指定 Model
const openai = ai.getProvider("openai");
const model = openai("gpt-5");

🦄 最佳實踐： 除非你的插件有特殊需求（例如僅支援特定 Provider 的功能），否則應優先使用 getDefaultModel() 來取得使用者的偏好模型。

---

generateText() — 基本文字生成

使用指定模型生成文字回應。

基本用法（prompt）

const ai = eagle.extraModule.ai;
const { generateText } = ai;

// 使用預設語言模型
const model = ai.getModel(ai.getDefaultModel("chat"));

const result = await generateText({
    model,
    prompt: "請幫我寫一個關於數位藝術的創意簡介",
});

console.log(result.text);

使用 messages 陣列

透過 messages 可以設定系統提示詞與多輪對話：

const model = ai.getModel(ai.getDefaultModel("chat"));

const result = await generateText({
    model,
    messages: [
        {
            role: "system",
            content: "你是一位專業的藝術評論家。",
        },
        {
            role: "user",
            content: "請分析印象派的色彩運用特點。",
        },
    ],
});

console.log(result.text);

多模態（文字 + 圖片）

// 使用預設視覺模型（支援圖片理解）
const model = ai.getModel(ai.getDefaultModel("image"));

const result = await generateText({
    model,
    messages: [
        {
            role: "user",
            content: [
                {
                    type: "text",
                    text: "請描述這張圖片的內容",
                },
                {
                    type: "image",
                    image: "https://example.com/sample-image.jpg",
                },
            ],
        },
    ],
});

console.log(result.text);

更多 generateText 的進階用法（如 maxTokens、temperature 等參數），請參考 AI SDK 官方文件。

---

generateObject() — 結構化物件生成

讓 AI 依照指定的 Schema 回傳結構化 JSON 物件。

使用 Zod Schema

const ai = eagle.extraModule.ai;
const { generateObject } = ai;
const { z } = require("zod");

// 純文字任務使用預設語言模型
const model = ai.getModel(ai.getDefaultModel("chat"));

const result = await generateObject({
    model,
    schema: z.object({
        tags: z.array(z.object({
            name: z.string(),
            reason: z.string(),
        })),
        description: z.string(),
    }),
    prompt: "請為一張日落海灘的照片生成 5 個標籤和描述",
});

console.log(result.object.tags);
console.log(result.object.description);

使用 JSON Schema

const model = ai.getModel(ai.getDefaultModel("chat"));

const result = await generateObject({
    model,
    schema: {
        type: "object",
        properties: {
            tags: {
                type: "array",
                items: {
                    type: "object",
                    properties: {
                        name: { type: "string" },
                        reason: { type: "string" },
                    },
                },
            },
            description: { type: "string" },
        },
    },
    prompt: "請為一張日落海灘的照片生成 5 個標籤和描述",
});

console.log(result.object.tags);
console.log(result.object.description);

圖片分析範例

// 涉及圖片理解，使用預設視覺模型
const model = ai.getModel(ai.getDefaultModel("image"));

const result = await generateObject({
    model,
    schema: {
        type: "object",
        properties: {
            colors: { type: "array", items: { type: "string" } },
            style: { type: "string" },
            mood: { type: "string" },
        },
    },
    messages: [
        {
            role: "system",
            content: "你是一個專業的圖像分析專家。",
        },
        {
            role: "user",
            content: [
                { type: "text", text: "請分析這張圖片的色彩、風格和情感。" },
                { type: "image", image: "https://example.com/artwork.jpg" },
            ],
        },
    ],
});

console.log(result.object);

更多 generateObject 的進階用法，請參考 AI SDK 官方文件。

---

streamText() — 串流文字生成

以串流方式逐步接收 AI 回應，適合需要即時顯示結果的場景。

const ai = eagle.extraModule.ai;
const { streamText } = ai;
const model = ai.getModel(ai.getDefaultModel("chat"));

const { textStream } = streamText({
    model,
    prompt: "請詳細介紹數位藝術的發展歷程",
});

// 使用非同步迭代器逐步接收文字
for await (const textPart of textStream) {
    console.log(textPart); // 即時顯示
}

即時顯示在 UI 中

let fullText = "";

const { textStream } = streamText({
    model,
    prompt: "請撰寫一篇短文",
});

for await (const textPart of textStream) {
    fullText += textPart;
    // 更新 UI 元素
    document.getElementById("output").textContent = fullText;
}

更多 streamText 的進階用法，請參考 AI SDK 官方文件。

---

streamObject() — 串流物件生成

以串流方式逐步接收結構化物件，每次迭代會收到目前已解析的部分物件。

const ai = eagle.extraModule.ai;
const { streamObject } = ai;
const model = ai.getModel(ai.getDefaultModel("chat"));

const { partialObjectStream } = streamObject({
    model,
    schema: {
        type: "object",
        properties: {
            analysis: {
                type: "object",
                properties: {
                    colors: { type: "array", items: { type: "string" } },
                    style: { type: "string" },
                    mood: { type: "string" },
                    suggestions: { type: "array", items: { type: "string" } },
                },
            },
        },
    },
    prompt: "請分析這件藝術作品的色彩、風格、情感，並提供改進建議。",
});

for await (const partialObject of partialObjectStream) {
    console.log("目前結果:", partialObject);
    // partialObject 會逐步增加欄位，例如：
    // { analysis: { colors: ["紅"] } }
    // { analysis: { colors: ["紅", "藍"], style: "印象派" } }
    // { analysis: { colors: ["紅", "藍"], style: "印象派", mood: "寧靜" } }
}

🦄 最佳實踐： streamObject 適合需要在 UI 上漸進式顯示分析結果的場景，讓使用者能在 AI 尚未完成時就看到部分結果。

更多 streamObject 的進階用法，請參考 AI SDK 官方文件。

---

Provider 管理方法

以下方法皆為同步方法，無需使用 await。

---

getProviders()

取得所有已註冊的 Provider 陣列。

• 返回 ProviderFunction[] — 所有 Provider 的陣列

const ai = eagle.extraModule.ai;

// ✅ 正確：回傳陣列
const providers = ai.getProviders();
console.log(providers.length); // 8

providers.forEach(provider => {
    console.log(provider.name); // "openai", "anthropic", "google", ...
});

注意： getProviders() 回傳的是陣列，不是物件。以下寫法是錯誤的：

// ❌ 錯誤：不可以解構為物件
const { openai, anthropic } = ai.getProviders();

// ❌ 錯誤：不需要 await
const providers = await ai.getProviders();

---

getProvider(providerName)

取得指定名稱的 Provider。

• providerName string — Provider 名稱（如 "openai"、"google"）

• 返回 ProviderFunction | undefined — 找到的 Provider，若不存在則回傳 undefined

const openai = ai.getProvider("openai");
const google = ai.getProvider("google");

if (openai) {
    const model = openai("gpt-5");
}

如果需要取得特定 Provider，建議使用 getProvider() 而非 getProviders()，程式碼更簡潔清晰。但在多數情況下，直接使用 getDefaultModel() 是更好的選擇。

---

getAvailableProviders()

取得所有已配置（使用者已完成設定）的 Provider。

• 返回 ProviderFunction[] — 已配置的 Provider 陣列

const available = ai.getAvailableProviders();

if (available.length === 0) {
    console.log("尚未配置任何 AI 提供者，請先在 AI SDK 設定中配置。");
} else {
    console.log(`已配置 ${available.length} 個提供者：`);
    available.forEach(p => console.log(`- ${p.name}`));
}

此方法與 getProviders() 的差異在於：getProviders() 回傳所有 8 個 Provider（含未配置的），getAvailableProviders() 僅回傳使用者已完成設定的 Provider。

---

getModel(providerAndModel)

透過 provider::model 格式直接取得模型實例。

• providerAndModel string — 格式為 "provider::model"

• 返回 Model — 可直接傳入 generateText() 等方法的模型物件

// 直接取得模型
const model = ai.getModel("openai::gpt-5");

const result = await generateText({
    model: model,
    prompt: "Hello!",
});

注意： 必須使用 :: 雙冒號分隔 Provider 與 Model 名稱，否則會拋出錯誤。

---

設定與刷新

---

open()

開啟偏好設置中的「AI 模型套件」設定面板。適合在插件介面中提供「模型設置」按鈕，讓使用者快速配置模型服務提供商與預設模型。

• 返回 void

const ai = eagle.extraModule.ai;

// 例如：在插件介面中放置「模型設置」按鈕
document.getElementById("settings-btn").addEventListener("click", () => {
    ai.open(); // 系統會自動彈出偏好設置中的模型設定區塊
});

🦄 最佳實踐： 當 getDefaultModel() 回傳 undefined（使用者尚未設定預設模型）時，可以在插件介面中顯示提示並提供按鈕呼叫 open()，引導使用者完成設定。

---

reload()

重新載入 AI SDK 配置。當使用者透過 open() 開啟設定面板並調整配置後，呼叫此方法即可讀取到最新的配置。

• 返回 void

const ai = eagle.extraModule.ai;

// 引導使用者設定後，刷新配置
ai.open();

// 使用者完成設定後，刷新以取得最新配置
ai.reload();

const defaultLLM = ai.getDefaultModel("chat"); // 取得使用者剛設定的模型

open() 不會阻塞程式執行，系統無法得知使用者何時完成設定。建議在需要使用模型時呼叫 reload() 確保讀取到最新配置。

---

預設模型方法

AI SDK 支援設定和讀取預設模型，讓使用者可以在偏好設置的「AI 模型套件」中統一指定偏好的模型。

---

getDefaultModel(type)

取得指定類型的預設模型。此為同步方法。

• type string — 模型類型，可選值："chat"（語言模型）或 "image"（視覺模型）

• 返回 string | undefined — 預設模型的 "provider::model" 字串，若未設定則回傳 undefined

// 取得使用者的預設語言模型
const defaultLLM = ai.getDefaultModel("chat");

if (defaultLLM) {
    console.log(`預設語言模型：${defaultLLM}`); // "openai::gpt-5"
    const model = ai.getModel(defaultLLM);
    const result = await generateText({ model, prompt: "Hello!" });
}

// 取得使用者的預設視覺模型
const defaultVLM = ai.getDefaultModel("image");

if (defaultVLM) {
    console.log(`預設視覺模型：${defaultVLM}`); // "openai::dall-e-3"
}

使用者可以在偏好設置的「AI 模型套件」中分別選擇偏好的語言模型（"chat"）和視覺模型（"image"），插件可各取所需。

---

Provider 實例方法

透過 getProvider() 取得的 Provider 實例，除了可作為函式呼叫來取得 Model 之外，還提供以下方法。

---

verify()

驗證 Provider 的連線與認證是否有效。用來檢查使用者目前的配置是否能正常連線。

• 返回 Promise<VerifyResult> — 驗證結果物件

  • ok boolean — 驗證是否成功

  • error APIError（可選） — 失敗時的錯誤詳情

const openai = ai.getProvider("openai");

const result = await openai.verify();

if (result.ok) {
    console.log("連線成功！");
} else {
    console.error("連線失敗：", result.error.message);
    console.error("HTTP 狀態碼：", result.error.status);
}

注意： verify() 回傳的不是 boolean，而是包含 ok 和 error 的物件。

// ❌ 錯誤
const isValid = await openai.verify();
if (isValid) { ... }

// ✅ 正確
const result = await openai.verify();
if (result.ok) { ... }

---

getModels()

取得此 Provider 所有可用的模型列表。

• 返回 Promise<string[]> — 模型 ID 陣列

const openai = ai.getProvider("openai");
const models = await openai.getModels();

console.log(models);
// ["gpt-5.2", "gpt-5", "o3", ...]

此方法會向 Provider 的 API 發送請求，請確保使用者已完成該 Provider 的配置。若未配置，會拋出 APIError。

---

hasModel(modelId)

檢查此 Provider 是否包含指定模型。

• modelId string — 模型 ID（如 "gpt-5"）

• 返回 Promise<boolean> — 是否存在

const openai = ai.getProvider("openai");
const exists = await openai.hasModel("gpt-5");

if (exists) {
    console.log("此模型可用");
}

---

Provider 實例屬性

以下為 Provider 實例的唯讀屬性：

---

name string

Provider 的名稱。

const openai = ai.getProvider("openai");
console.log(openai.name); // "openai"

---

baseURL string | undefined

目前設定的 API 端點。

const openai = ai.getProvider("openai");
console.log(openai.baseURL); // "https://api.openai.com" 或 undefined

---

支援的 Provider 一覽表

Provider	名稱	類型	預設 Base URL
OpenAI	"openai"	商業（雲端）	需手動設定
Anthropic	"anthropic"	商業（雲端）	需手動設定
Google Gemini	"google"	商業（雲端）	需手動設定
DeepSeek	"deepseek"	商業（雲端）	需手動設定
通義千問	"tongyi"	商業（雲端）	https://dashscope.aliyuncs.com/compatible-mode/v1
Ollama	"ollama"	本地	http://localhost:11434/v1
LM Studio	"lmstudio"	本地	http://localhost:1234/v1
OpenAI Compatible	"openai-compatible"	自訂（相容協議）	需手動設定（API Key 選填）

OpenAI Compatible 適用於所有相容 OpenAI API 協議的服務。使用者只需提供 Base URL，API Key 為選填（部分雲端服務需要，本地服務通常不需要）。系統會自動在 URL 末尾補上 /v1（若尚未包含）。

注意： Google Gemini 的 Provider 名稱是 "google"，不是 "gemini"。

// ✅ 正確
const google = ai.getProvider("google");
ai.getModel("google::gemini-3-flash");

// ❌ 錯誤
const gemini = ai.getProvider("gemini");
ai.getModel("gemini::gemini-3-flash");

---

錯誤處理

APIError 類別

AI SDK 在 API 請求失敗時會拋出 APIError，包含完整的錯誤資訊。

屬性

屬性	型別	說明
message	string	錯誤訊息
status	number | undefined	HTTP 狀態碼（如 401、403、500）
statusText	string | undefined	HTTP 狀態文字（如 "Unauthorized"）
code	string | undefined	錯誤碼（從回應內容中提取）
provider	string | undefined	Provider 名稱
url	string | undefined	請求的 URL
responseBody	unknown	伺服器回傳的原始錯誤內容

方法

方法	說明
toJSON()	回傳完整錯誤詳情物件（適合記錄日誌）
toString()	回傳錯誤訊息字串

錯誤處理範例

const ai = eagle.extraModule.ai;
const { generateText, APIError } = ai;

try {
    const model = ai.getModel(ai.getDefaultModel("chat"));
    const result = await generateText({
        model,
        prompt: "Hello!",
    });
    console.log(result.text);
} catch (error) {
    if (error instanceof APIError) {
        console.error("API 錯誤：", error.message);
        console.error("狀態碼：", error.status);       // 401, 429, 500...
        console.error("Provider：", error.provider);    // "openai"

        // 根據狀態碼處理
        switch (error.status) {
            case 401:
                console.error("API Key 無效，請檢查 AI SDK 設定");
                break;
            case 429:
                console.error("請求頻率過高，請稍後再試");
                break;
            case 500:
                console.error("伺服器內部錯誤");
                break;
        }

        // 記錄完整日誌
        console.log(JSON.stringify(error.toJSON(), null, 2));
    } else {
        console.error("非預期錯誤：", error);
    }
}

網路錯誤

當無法連線到 Provider 時（如本地 Ollama 未啟動），也會收到 APIError：

const ollama = ai.getProvider("ollama");
const result = await ollama.verify();

if (!result.ok) {
    console.error(result.error.message);
    // "[ollama] Network error: fetch failed"
}

---

最佳實踐

1. 優先使用預設模型

這是最重要的建議。使用 getDefaultModel() 直接繼承使用者在 AI SDK 設定介面中的偏好，而非在程式碼中寫死特定的 Provider 和模型：

const ai = eagle.extraModule.ai;
const { generateText } = ai;

// ⭐ 推薦：使用者已在 AI SDK 中設定好偏好模型
const defaultLLM = ai.getDefaultModel("chat");

if (!defaultLLM) {
    console.log("請先在 AI SDK 設定中選擇預設語言模型");
    return;
}

const model = ai.getModel(defaultLLM);
const result = await generateText({ model, prompt: "..." });

為什麼不要寫死模型？ 如果你在程式碼中指定 ai.getProvider("openai")("gpt-5")，但使用者沒有配置 OpenAI，就會出錯。你需要額外處理「Provider 未配置」的邊界情況，這很麻煩。使用預設模型則能保證使用者已經配置並驗證過，省去大量防禦性程式碼。

2. 正確處理 verify() 結果

// ✅ 正確：檢查 result.ok
const result = await openai.verify();
if (result.ok) {
    // 連線成功
} else {
    console.error(result.error.message);
}

// ❌ 錯誤：不要直接當 boolean 使用
if (await openai.verify()) { ... }

3. 串流適用於長文本生成

當預期回應較長時，使用 streamText() 提供更好的使用者體驗：

const { textStream } = streamText({
    model: ai.getModel(ai.getDefaultModel("chat")),
    prompt: longPrompt,
});

for await (const chunk of textStream) {
    appendToUI(chunk);
}

---

完整範例

以下為一個綜合性的插件範例，展示如何正確使用 AI SDK 的主要功能：

eagle.onPluginCreate(async (plugin) => {
    const ai = eagle.extraModule.ai;
    const { generateText, generateObject, streamText, APIError } = ai;

    // 1. 取得使用者在偏好設置中選擇的預設語言模型
    const defaultLLM = ai.getDefaultModel("chat");

    if (!defaultLLM) {
        console.log("請先在 AI SDK 設定中選擇預設語言模型");
        return;
    }

    const model = ai.getModel(defaultLLM);
    console.log(`使用預設模型：${defaultLLM}`);

    // 2. 基本文字生成
    try {
        const result = await generateText({
            model,
            prompt: "請用一句話描述這個插件的功能",
        });
        console.log("生成結果：", result.text);
    } catch (error) {
        if (error instanceof APIError) {
            console.error(`API 錯誤 [${error.status}]：${error.message}`);
        }
    }

    // 3. 結構化物件生成
    try {
        const result = await generateObject({
            model,
            schema: {
                type: "object",
                properties: {
                    tags: { type: "array", items: { type: "string" } },
                    category: { type: "string" },
                },
            },
            prompt: "請為一張貓咪照片生成 3 個標籤和分類",
        });
        console.log("標籤：", result.object.tags);
        console.log("分類：", result.object.category);
    } catch (error) {
        console.error("物件生成失敗：", error.message);
    }

    // 4. 串流文字生成
    try {
        const { textStream } = streamText({
            model,
            prompt: "請列出 5 個數位藝術的創作技巧",
        });

        let fullText = "";
        for await (const chunk of textStream) {
            fullText += chunk;
        }
        console.log("串流結果：", fullText);
    } catch (error) {
        console.error("串流生成失敗：", error.message);
    }
});

---

API 速查表

AI SDK 頂層方法

方法	同步/非同步	回傳型別	說明
getProviders()	同步	ProviderFunction[]	取得所有 Provider
getProvider(name)	同步	ProviderFunction | undefined	取得指定 Provider
getAvailableProviders()	同步	ProviderFunction[]	取得已配置的 Provider
getModel(provider::model)	同步	Model	取得模型實例
getDefaultModel(type)	同步	string | undefined	取得預設模型
open()	同步	void	開啟偏好設置的模型設定面板
reload()	同步	void	重新載入最新配置
generateText(options)	非同步	Promise<GenerateTextResult>	生成文字
generateObject(options)	非同步	Promise<GenerateObjectResult>	生成結構化物件
streamText(options)	非同步	StreamTextResult	串流文字生成
streamObject(options)	非同步	StreamObjectResult	串流物件生成

Provider 實例方法

方法	同步/非同步	回傳型別	說明
provider(modelId)	同步	Model	取得模型（函式呼叫）
verify()	非同步	Promise<VerifyResult>	驗證連線與認證
getModels()	非同步	Promise<string[]>	取得模型列表
hasModel(modelId)	非同步	Promise<boolean>	檢查模型是否存在

Provider 實例屬性

屬性	型別	說明
name	string	Provider 名稱（唯讀）
baseURL	string | undefined	API 端點（唯讀）

VerifyResult

屬性	型別	說明
ok	boolean	驗證是否成功
error	APIError | undefined	失敗時的錯誤物件