編寫 Genkit 外掛程式

Firebase Genkit 的功能可透過外掛程式擴充。Genkit 外掛程式是可設定的模組，可提供模型、擷取器、索引器、追蹤儲存空間等。您已經透過 Genkit 看到外掛程式的運作情形：

import { genkit } from 'genkit';
import { vertexAI } from '@genkit-ai/vertexai';

const ai = genkit({
  plugins: [vertexAI({ projectId: 'my-project' })],
});

Vertex AI 外掛程式會採用設定 (例如使用者的 Google Cloud 專案 ID)，並將各種新模型、嵌入程式等註冊至 Genkit 註冊中心。此登錄可為 Genkit 的本機 UI 提供動力，用於執行及檢查模型、提示等，並在執行階段提供命名動作的查詢服務。

建立外掛程式

如要建立外掛程式，通常會建立新的 NPM 套件：

mkdir genkitx-my-plugin
cd genkitx-my-plugin
npm init -y
npm i --save genkit
npm i --save-dev typescript
npx tsc --init

接著，從主要進入點定義及匯出外掛程式：

import { Genkit, z } from 'genkit';
import { GenkitPlugin, genkitPlugin } from 'genkit/plugin';

interface MyPluginOptions {
  // add any plugin configuration here
}

export function myPlugin(options?: MyPluginOptions) {
  return genkitPlugin('myPlugin', async (ai: Genkit) => {
    ai.defineModel(...);
    ai.defineEmbedder(...)
    // ....
  });
};

外掛程式選項指南

一般來說，外掛程式應採用單一 options 引數，其中包含任何外掛程式全域設定，以便運作。對於需要密鑰值的任何外掛程式選項 (例如 API 金鑰)，您應提供選項和預設環境變數來設定：

import { Genkit, z } from 'genkit';
import { GenkitPlugin, genkitPlugin } from 'genkit/plugin';
import { GenkitError } from '@genkit-ai/core';

interface MyPluginOptions {
  apiKey?: string;
}

export function myPlugin(options?: MyPluginOptions) {
  return genkitPlugin('myPlugin', async (ai: Genkit) => {
    if (!apiKey)
      throw new GenkitError({
        source: 'my-plugin',
        status: 'INVALID_ARGUMENT',
        message:
          'Must supply either `options.apiKey` or set `MY_PLUGIN_API_KEY` environment variable.',
      });

    ai.defineModel(...);
    ai.defineEmbedder(...)
    
    // ....
  });
};

建構外掛程式

單一外掛程式就能在 Genkit 中啟用許多新功能。舉例來說，Vertex AI 外掛程式會啟用多個新模型，以及一個嵌入程式。

模型外掛程式

Genkit 模型外掛程式會將一或多個生成式 AI 模型新增至 Genkit 登錄表。模型代表任何生成式模型，可接收提示做為輸入內容，並產生文字、媒體或資料做為輸出內容。一般來說，模型外掛程式會在其初始化函式中發出一或多個 defineModel 呼叫。

自訂模型通常包含三個元件：

  1. 定義模型功能的中繼資料。
  2. 設定結構定義，其中包含模型支援的任何特定參數。
  3. 實作模型的函式，可接受 GenerateRequest 並傳回 GenerateResponse。

如要建構模型外掛程式，您必須使用 @genkit-ai/ai 套件：

npm i --save @genkit-ai/ai

大致來說，模型外掛程式可能如下所示：

import { genkitPlugin, GenkitPlugin } from 'genkit/plugin';
import { GenkitError } from '@genkit-ai/core';
import { GenerationCommonConfigSchema } from '@genkit-ai/ai/model';
import { simulateSystemPrompt } from '@genkit-ai/ai/model/middleware';
import { z } from 'genkit';


export function myPlugin(options?: MyPluginOptions) {
  return genkitPlugin('my-plugin', async (ai: Genkit) => {
    ai.defineModel({
      // be sure to include your plugin as a provider prefix
      name: 'my-plugin/my-model',
      // label for your model as shown in Genkit Developer UI
      label: 'My Awesome Model',
      // optional list of supported versions of your model
      versions: ['my-model-001', 'my-model-001'],
      // model support attributes
      supports: {
        multiturn: true, // true if your model supports conversations
        media: true, // true if your model supports multimodal input
        tools: true, // true if your model supports tool/function calling
        systemRole: true, // true if your model supports the system role
        output: ['text', 'media', 'json'], // types of output your model supports
      },
      // Zod schema for your model's custom configuration
      configSchema: GenerationCommonConfigSchema.extend({
        safetySettings: z.object({...}),
      }),
      // list of middleware for your model to use
      use: [simulateSystemPrompt()]
    }, async request => {
      const myModelRequest = toMyModelRequest(request);
      const myModelResponse = await myModelApi(myModelRequest);
      return toGenerateResponse(myModelResponse);
    });
  });
};

轉換要求和回應

Genkit 模型外掛程式的主要工作，是將 Genkit 的一般格式 GenerateRequest 轉換為模型 API 可辨識及支援的格式，然後將模型的回應轉換為 Genkit 使用的 GenerateResponseData 格式。

有時，您可能需要調整或操縱資料，以因應模型限制。舉例來說，如果模型本身不支援 system 訊息，您可能需要將提示的系統訊息轉換為使用者/模型訊息組合。

模型參考資料

使用 defineModel 註冊模型後，只要以名稱要求模型，系統就會一律提供該模型。不過，為了改善輸入和 IDE 自動完成功能，您可以從套件中匯出模型參照，該參照只包含模型的中繼資料，而非其實作內容：

import { modelRef } from "@genkit-ai/ai/model";

export myModelRef = modelRef({
  name: "my-plugin/my-model",
  configSchema: MyConfigSchema,
  info: {
    // ... model-specific info
  },
})

呼叫 generate() 時，模型參照和字串模型名稱可互換使用：

import { myModelRef } from 'genkitx-my-plugin';
import { generate } from '@genkit-ai/ai';

generate({ model: myModelRef });
// is equivalent to
generate({ model: 'my-plugin/my-model' });

發布外掛程式

Genkit 外掛程式可做為一般 NPM 套件發布。為提高可發現性並盡可能提高一致性，您的套件應命名為 genkitx-{name}，以表示這是 Genkit 外掛程式，並在 package.json 中加入與外掛程式相關的以下 keywords：

  • genkit-plugin：請務必在套件中加入這個關鍵字，表示這是 Genkit 外掛程式。
  • genkit-model：如果套件定義任何模型，請加入這個關鍵字。
  • genkit-retriever：如果套件定義了任何擷取器，請加入這個關鍵字。
  • genkit-indexer：如果套件定義任何索引器，請加入這個關鍵字。
  • genkit-embedder：如果套件定義任何索引器，請加入這個關鍵字。
  • genkit-tracestore：如果套件定義了任何追蹤儲存庫，請加入這個關鍵字。
  • genkit-statestore：如果套件定義任何狀態儲存庫，請加入這個關鍵字。
  • genkit-telemetry：如果套件定義了遙測供應工具，請加入這個關鍵字。
  • genkit-deploy：如果套件包含協助程式，可將 Genkit 應用程式部署至雲端服務供應商，請加入這個關鍵字。
  • genkit-flow：如果套件可強化 Genkit 流程，請加入這個關鍵字。

提供擷取器、嵌入器和模型的外掛程式可能會有類似以下的 package.json：

{
  "name": "genkitx-my-plugin",
  "keywords": ["genkit-plugin", "genkit-retriever", "genkit-embedder", "genkit-model"],
  // ... dependencies etc.
}