Cómo escribir complementos de Genkit

Las funciones de Firebase Genkit están diseñadas para que se extiendan a través de complementos. Los complementos de Genkit son módulos configurables que pueden proporcionar modelos, recuperadores, indexadores, almacenes de seguimientos y mucho más. Ya viste los complementos en acción con solo usar Genkit:

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

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

El complemento de Vertex AI toma la configuración (como el ID del proyecto de Google Cloud del usuario) y registra una variedad de nuevos modelos, incorporadores y más con el registro de Genkit. El registro potencia la IU local de Genkit para ejecutar e inspeccionar modelos, instrucciones y mucho más, y también sirve como un servicio de búsqueda para acciones con nombre en el entorno de ejecución.

Cómo crear un complemento

Para crear un complemento, generalmente, querrás crear un nuevo paquete de NPM:

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

Luego, define y exporta tu complemento desde tu punto de entrada principal:

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(...)
    // ....
  });
};

Orientación sobre las opciones de complementos

En general, tu complemento debe aceptar un solo argumento options que incluya cualquier configuración general del complemento necesaria para funcionar. Para cualquier opción de complemento que requiera un valor secreto, como claves de API, debes ofrecer una opción y una variable de entorno predeterminada para configurarla:

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(...)
    
    // ....
  });
};

Cómo compilar tu complemento

Un solo complemento puede activar muchos elementos nuevos en Genkit. Por ejemplo, el complemento de Vertex AI activa varios modelos nuevos, así como un incorporador.

Complementos de modelos

Los complementos de modelos de Genkit agregan uno o más modelos de IA generativa al registro de Genkit. Un modelo representa cualquier modelo generativo capaz de recibir una instrucción como entrada y generar texto, contenido multimedia o datos como resultados. Por lo general, un complemento de modelo realizará una o más llamadas defineModel en su función de inicialización.

En general, un modelo personalizado consta de tres componentes:

  1. Metadatos que definen las capacidades del modelo.
  2. Un esquema de configuración con cualquier parámetro específico que el modelo admita.
  3. Una función que implementa el modelo que acepta GenerateRequest y muestra GenerateResponse.

Para compilar un complemento de modelo, deberás usar el paquete @genkit-ai/ai:

npm i --save @genkit-ai/ai

En términos generales, un complemento de modelo podría verse de la siguiente manera:

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);
    });
  });
};

Transformación de solicitudes y respuestas

El trabajo principal de un complemento de modelo de Genkit es transformar la GenerateRequest del formato común de Genkit en un formato que reconozca y admita la API de tu modelo y, luego, transformar la respuesta de tu modelo al formato GenerateResponseData que usa Genkit.

A veces, esto puede requerir reorganizar o manipular datos para evitar las limitaciones del modelo. Por ejemplo, si tu modelo no admite de forma nativa un mensaje system, quizás debas transformar el mensaje del sistema de una instrucción en un par de mensajes usuario-modelo.

Referencias de modelos

Una vez que un modelo se registra con defineModel, siempre está disponible cuando se solicita por nombre. Sin embargo, para mejorar la escritura y la finalización automática del IDE, puedes importar una referencia de modelo desde tu paquete que incluya solo los metadatos de un modelo, pero no su implementación:

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

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

Cuando llames a generate(), las referencias de modelos y los nombres de modelos de cadenas se pueden usar indistintamente:

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

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

Cómo publicar un complemento

Los complementos de Genkit se pueden publicar como paquetes normales de NPM. Para aumentar la visibilidad y maximizar la coherencia, tu paquete debe llamarse genkitx-{name} para indicar que es un complemento de Genkit y debes incluir tantos de los siguientes keywords en tu package.json como sean relevantes para tu complemento:

  • genkit-plugin: Siempre incluye esta palabra clave en tu paquete para indicar que es un complemento de Genkit.
  • genkit-model: Incluye esta palabra clave si tu paquete define algún modelo.
  • genkit-retriever: Incluye esta palabra clave si tu paquete define algún recuperador.
  • genkit-indexer: Incluye esta palabra clave si tu paquete define algún indexador.
  • genkit-embedder: Incluye esta palabra clave si tu paquete define algún indexador.
  • genkit-tracestore: Incluye esta palabra clave si tu paquete define algún almacén de seguimiento.
  • genkit-statestore: Incluye esta palabra clave si tu paquete define algún almacén de estado.
  • genkit-telemetry: Incluye esta palabra clave si tu paquete define un proveedor de telemetría.
  • genkit-deploy: Incluye esta palabra clave si tu paquete incluye ayudantes para implementar apps de Genkit en proveedores de servicios en la nube.
  • genkit-flow: Incluye esta palabra clave si tu paquete mejora los flujos de Genkit.

Un complemento que proporcionó un recuperador, un incorporador y un modelo podría tener un package.json que se vea de la siguiente manera:

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