> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 AI SDK 搭配 CometAPI

> 使用本指南透過設定 base URL、API key，以及 model 或 provider 選項，來設定 AI SDK 與 CometAPI。

[適用於 AI SDK 的 CometAPI provider](https://github.com/cometapi-dev/ai-sdk-provider) 透過統一的 TypeScript 介面，讓你可以存取 500+ 個 AI 模型。你可以使用它為任何 Node.js 或 Edge runtime 應用程式加入文字生成、串流、嵌入，以及圖片生成能力。

## 支援功能

| 功能   | 方法                     | 狀態 |
| ---- | ---------------------- | -- |
| 文字生成 | `generateText()`       | 支援 |
| 文字串流 | `streamText()`         | 支援 |
| 文字嵌入 | `textEmbeddingModel()` | 支援 |
| 圖片生成 | `imageModel()`         | 支援 |

## 先決條件

* Node.js 18+
* 具有有效 API key 的 CometAPI 帳戶 — [在這裡取得](https://www.cometapi.com/console/token)

<Steps>
  <Step title="安裝 provider">
    安裝 `@cometapi/ai-sdk-provider` 以及 AI SDK 核心套件：

    <CodeGroup>
      ```bash npm theme={null}
      npm install @cometapi/ai-sdk-provider ai
      ```

      ```bash pnpm theme={null}
      pnpm add @cometapi/ai-sdk-provider ai
      ```

      ```bash yarn theme={null}
      yarn add @cometapi/ai-sdk-provider ai
      ```
    </CodeGroup>
  </Step>

  <Step title="設定你的 API key">
    provider 預設會讀取 `COMETAPI_KEY` 環境變數：

    ```bash theme={null}
    read -rsp "CometAPI API key: " COMETAPI_KEY
    printf '\n'
    export COMETAPI_KEY
    ```

    <Note>
      使用環境變數可避免在原始碼中硬編碼憑證。
    </Note>
  </Step>

  <Step title="匯入 provider">
    匯入預設的 provider 實例：

    ```typescript theme={null}
    import { cometapi } from '@cometapi/ai-sdk-provider';
    ```

    若要覆寫 API key、base URL 或其他設定，請使用 `createCometAPI`：

    ```typescript theme={null}
    import { createCometAPI } from '@cometapi/ai-sdk-provider';

    const cometapi = createCometAPI({
      apiKey: process.env.COMETAPI_KEY,       // override env variable
      baseURL: 'https://api.cometapi.com/v1',  // default
    });
    ```
  </Step>
</Steps>

## 用法

### 生成文字

使用 `generateText()` 來取得單次回應：

```typescript theme={null}
import { cometapi } from '@cometapi/ai-sdk-provider';
import { generateText } from 'ai';

const { text } = await generateText({
  model: cometapi('your-model-id'),
  prompt: 'What is CometAPI?',
});

console.log(text);
```

### 串流文字

使用 `streamText()` 取得即時分塊輸出：

```typescript theme={null}
import { cometapi } from '@cometapi/ai-sdk-provider';
import { streamText } from 'ai';

const result = streamText({
  model: cometapi('your-model-id'),
  prompt: 'Write a short story about AI.',
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}
```

### 生成嵌入

使用 `textEmbeddingModel()` 建立向量嵌入：

```typescript theme={null}
import { cometapi } from '@cometapi/ai-sdk-provider';

const model = cometapi.textEmbeddingModel('text-embedding-3-small');

// Single embedding
const single = await model.doEmbed({ values: ['Hello, world!'] });
console.log('Dimensions:', single.embeddings[0].length);

// Batch embeddings
const batch = await model.doEmbed({
  values: ['sunny day', 'rainy afternoon', 'cold winter night'],
});
console.log('Count:', batch.embeddings.length);
```

### 生成圖片

使用 `imageModel()` 根據文字 Prompt 生成圖片：

```typescript theme={null}
import { cometapi } from '@cometapi/ai-sdk-provider';
import { experimental_generateImage as generateImage } from 'ai';

const { image } = await generateImage({
  model: cometapi.imageModel('your-model-id'),
  prompt: 'A beautiful sunset over mountains',
});
```

## 提供者設定

`createCometAPI` 接受以下選項：

| 選項        | 類型                       | 預設值                           | 說明              |
| --------- | ------------------------ | ----------------------------- | --------------- |
| `apiKey`  | `string`                 | `process.env.COMETAPI_KEY`    | CometAPI API 金鑰 |
| `baseURL` | `string`                 | `https://api.cometapi.com/v1` | API 基礎 URL      |
| `headers` | `Record<string, string>` | —                             | 自訂請求標頭          |
| `fetch`   | `FetchFunction`          | —                             | 自訂 fetch 實作     |

## 模型方法

提供者公開了幾個模型建構函式：

| 方法                                     | 回傳                 | 使用情境            |
| -------------------------------------- | ------------------ | --------------- |
| `cometapi(modelId)`                    | `LanguageModelV2`  | 文字生成與串流（簡寫）     |
| `cometapi.chatModel(modelId)`          | `LanguageModelV2`  | 聊天補全            |
| `cometapi.completionModel(modelId)`    | `LanguageModelV2`  | 文字補全            |
| `cometapi.languageModel(modelId)`      | `LanguageModelV2`  | `chatModel` 的別名 |
| `cometapi.textEmbeddingModel(modelId)` | `EmbeddingModelV2` | 文字嵌入            |
| `cometapi.imageModel(modelId)`         | `ImageModelV2`     | 圖像生成            |

請在[模型頁面](/zh-Hant/overview/models)瀏覽完整的可用 model ID 清單。

<AccordionGroup>
  <Accordion title="提示與疑難排解">
    * **模型選擇**：來自 [CometAPI 模型目錄](/zh-Hant/overview/models) 的任何模型都可搭配對應的模型方法使用——聊天模型透過 `cometapi()`，嵌入模型透過 `textEmbeddingModel()`，圖像模型透過 `imageModel()`。
    * **微調回應**：將 `temperature`、`maxTokens` 和 `topP` 直接傳遞給 `generateText()` 或 `streamText()`，例如 `generateText(\{..., temperature: 0.7\})`。
    * **錯誤處理**：將呼叫包在 `try/catch` 中，以處理驗證錯誤、速率限制或網路問題。
    * **安全性**：切勿將 API 金鑰提交到版本控制。請使用環境變數或祕密管理工具。
    * **速率限制**：請在 [CometAPI 主控台](https://www.cometapi.com/console) 監控用量。
  </Accordion>
</AccordionGroup>

## 相關資源

* [GitHub 上的 CometAPI AI SDK Provider](https://github.com/cometapi-dev/ai-sdk-provider)
* [npm 上的 @cometapi/ai-sdk-provider](https://www.npmjs.com/package/@cometapi/ai-sdk-provider)
* [AI SDK 文件](https://ai-sdk.dev/docs)
* [CometAPI 快速開始](/zh-Hant/overview/quick-start)

<script type="application/ld+json">
  {`
    {
    "@context": "https://schema.org",
    "@graph": [
      {
        "@type": "HowTo",
        "@id": "https://apidoc.cometapi.com/integrations/ai-sdk#howto",
        "name": "使用 AI SDK 搭配 CometAPI",
        "description": "使用本指南，透過設定 base URL、API key，以及 model 或 provider 選項，來設定 AI SDK 與 CometAPI 搭配使用。",
        "step": [
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/ai-sdk#step-1",
            "position": 1,
            "name": "安裝 provider",
            "text": "完成「使用 AI SDK 搭配 CometAPI」指南中的「安裝 provider」步驟。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/ai-sdk#step-2",
            "position": 2,
            "name": "設定你的 API key",
            "text": "將你的 CometAPI API key 儲存在整合所使用的環境變數或設定欄位中。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/ai-sdk#step-3",
            "position": 3,
            "name": "匯入 provider",
            "text": "完成「使用 AI SDK 搭配 CometAPI」指南中的「匯入 provider」步驟。"
          }
        ]
      },
      {
        "@type": "BreadcrumbList",
        "itemListElement": [
          {
            "@type": "ListItem",
            "position": 1,
            "name": "CometAPI 文件",
            "item": "https://apidoc.cometapi.com/"
          },
          {
            "@type": "ListItem",
            "position": 2,
            "name": "整合",
            "item": "https://apidoc.cometapi.com/integrations"
          },
          {
            "@type": "ListItem",
            "position": 3,
            "name": "使用 AI SDK 搭配 CometAPI",
            "item": "https://apidoc.cometapi.com/integrations/ai-sdk"
          }
        ]
      }
    ]
    }
    `}
</script>