نوشتن پلاگین های 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 چندین مدل جدید و همچنین یک embedder را فعال می کند.

پلاگین های مدل

پلاگین های مدل Genkit یک یا چند مدل هوش مصنوعی مولد را به رجیستری 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 تبدیل 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 است و باید به همان تعداد از keywords زیر را که مربوط به افزونه شما هستند در package.json خود وارد کنید:

• 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.
}