כתיבת פלאגינים של 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) ומרשם מגוון מודלים חדשים, רכיבי הטמעה ועוד במרשם של Genkit. הרישום מפעיל את ממשק המשתמש המקומי של Genkit להפעלה ולבדיקה של מודלים, הנחיות ועוד, וגם משמש כשירות חיפוש של פעולות בעלות שם בזמן הריצה.

יצירת פלאגין

כדי ליצור פלאגין, בדרך כלל צריך ליצור חבילת 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 בפונקציית האי initialization שלו.

מודל מותאם אישית מורכב בדרך כלל משלושה רכיבים:

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 היא להמיר את הערך GenerateRequest מהפורמט הנפוץ של Genkit לפורמט שמזוהה ונתמך על ידי ה-API של המודל, ולאחר מכן להמיר את התשובה מהמודל לפורמט GenerateResponseData שבו משתמש Genkit.

לפעמים, כדי לעקוף את המגבלות של המודל, צריך לערוך או לבצע מניפולציות על הנתונים. לדוגמה, אם המודל לא תומך באופן מקורי בהודעה 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.
}