نقل البيانات من الإصدار 0.5

تُقدّم أداة Genkit 0.9 عددًا من التغييرات الأساسية إلى جانب تحسينات على الميزات التي تُحسِّن الوظائف بشكل عام. إذا كنت تعمل على تطوير التطبيقات باستخدام Genkit 0.5، عليك تعديل رمز تطبيقك عند الترقية إلى أحدث إصدار. يوضّح هذا الدليل التغييرات الأكثر أهمية ويقدّم خطوات لنقل تطبيقاتك الحالية بسلاسة.

دليل البدء السريع

ستساعدك الخطوات التالية في نقل البيانات من Genkit 0.5 إلى Genkit 0.9 بسرعة. يمكنك الاطّلاع على مزيد من المعلومات حول هذه التغييرات في سجلّ التغييرات المفصّل أدناه.

1- تثبيت وحدة تحكم سطر الأوامر الجديدة

• إلغاء تثبيت وحدة تحكم سطر الأوامر القديمة

  npm uninstall -g genkit && npm uninstall genkit
  

• تثبيت وحدة تحكم سطر الأوامر الجديدة

  npm i -D genkit-cli
  

2- تعديل التبعيات

• إزالة حِزم Genkit الأساسية الفردية

  npm uninstall @genkit-ai/ai @genkit-ai/core @genkit-ai/dotprompt @genkit-ai/flow
  

• تثبيت حزمة genkit المجمّعة الجديدة

  npm i --save genkit
  

• ترقية جميع إصدارات المكوّن الإضافي (مثال أدناه)

  npm upgrade @genkit-ai/firebase
  

3- تغيير عمليات الاستيراد

• إزالة عمليات الاستيراد لحِزم Genkit الأساسية الفردية

  import { … } from '@genkit-ai/ai';
  import { … } from '@genkit-ai/core';
  import { … } from '@genkit-ai/flow';
  

• إزالة عمليات استيراد zod

  import * as z from 'zod';
  

• استيراد genkit وzod من genkit

  import { z, genkit } from 'genkit';
  

4. تعديل الرمز

أزِل وحدات configureGenkit.

يتم الآن ضبط Genkit لكل مثيل. يتم ضبط بيانات القياس والتسجيل على مستوى النظام بشكل منفصل عن نسخة Genkit.

• استبدِل الوحدات configureGenkit بوحدات ai = genkit({...}). الاحتفاظ بإعدادات المكوّن الإضافي فقط

  import { genkit } from 'genkit';
  
  const ai = genkit({ plugins: [...]});
  

• ضبط بيانات القياس عن بُعد باستخدام enableFirebaseTelemetry أو enableGoogleCloudTelemetry

  بالنسبة إلى Firebase:

  import { enableFirebaseTelemetry } from '@genkit-ai/firebase';
  
  enableFirebaseTelemetry({...});
  

  بالنسبة إلى Google Cloud:

  import { enableGoogleCloudTelemetry } from '@genkit-ai/google-cloud';
  
  enableGoogleCloudTelemetry({...});
  

• اضبط مستوى التسجيل بشكل مستقل ```js import { logger } from 'genkit/logging';

  logger.setLogLevel('debug'); ```

اطّلِع على مستندات المراقبة والتسجيل للحصول على مزيد من التفاصيل حول كيفية ضبط ميزة "إحصاءات الاستخدام" وميزة "تسجيل البيانات".

اطّلِع على مستندات البدء للحصول على مزيد من التفاصيل حول كيفية ضبط إعدادات مثيل Genkit.

نقل إجراءات Genkit ليتمّ استدعاؤها من مثيل genkit

يتم تحديد الإجراءات (عمليات المعالجة والأدوات وأدوات الاسترجاع والموسّعات وغير ذلك) لكلّ مثيل. اطّلِع على سجلّ التغييرات لمعرفة جميع الميزات التي عليك تغييرها، ولكن إليك مثالاً على بعض الميزات الشائعة.

import { genkit } from 'genkit';
import { onFlow } from '@genkit-ai/firebase/functions';

const ai = genkit({ plugins: [...]});

// Flows and tools are defined on the specific genkit instance
// and are directly callable.
const sampleFlow = ai.defineFlow(...);
const sampleTool = ai.defineTool(...);

async function callMyFlow() {
  // Previously, text output could accessed via .text()
  // Now it is either .output() or .text
  return await sampleFlow().output();
}

// onFlow now takes the Genkit instance as first argument
// This registers the flow as a callable firebase function
onFlow(ai, ...);
const flows = [ sampleFlow, ... ];
// Start the flow server to make the registered flows callable over HTTP
ai.startFlowServer({flows});

5- تشغيله

# run the DevUI and your js code
genkit start -- <command to run node>
# run a defined flow
genkit flow:run <flowName>

سجلّ التغييرات

1- التغييرات في واجهة سطر الأوامر

تم إجراء تعديلات كبيرة على واجهة سطر الأوامر (CLI) في الإصدار 0.9 من Genkit. تم تغيير الأمر لبدء Genkit، وتم فصل واجهة برمجة التطبيقات (CLI) إلى حزمة مستقلة، ويجب الآن تثبيتها بشكل منفصل.

لتثبيت سطر الأوامر، اتّبِع الخطوات التالية:

npm i -g genkit-cli

تم إجراء بعض التغييرات على الأمر genkit start:

بدء رمز تطبيق Genkit + واجهة مستخدم المطوّر معًا:

genkit start -- [start command]
genkit start -- tsx src/index.ts
genkit start -- go run main.go

يتوفّر أيضًا وضع المشاهدة:

genkit start -- tsx --watch src/index.ts

بدء رمز تطبيقك فقط في وضع المطوّر في Genkit:

genkit start --noui -- <start command>
genkit start --noui -- tsx src/index.ts

بدء واجهة مستخدم المطوّر فقط:

genkit start

في السابق، كان الأمر genkit start يشغّل واجهة مستخدم المطوّر ورمز تطبيقك معًا. إذا كانت لديك أيّ مسارات معالجة للتكامل المستمر/النشر الدائم تعتمد على هذا الأمر، قد تحتاج إلى تعديل مسار المعالجة.

ستتفاعل واجهة مستخدم المطوّر مباشرةً مع خادم مسار الإحالة الناجحة لمعرفة مسارات الإحالة الناجحة المسجّلة والسماح لك بتشغيلها مباشرةً باستخدام نماذج الإدخال.

2- الحِزم والواردات المبسّطة

في السابق، كانت مكتبات Genkit مُقسّمة إلى عدة وحدات كان عليك تثبيتها واستيرادها بشكلٍ فردي. تم الآن دمج هذه الوحدات في عملية استيراد واحدة. بالإضافة إلى ذلك، يعيد Genkit الآن تصدير وحدة Zod.

القديم:

npm i @genkit-ai/core @genkit-ai/ai @genkit-ai/flow @genkit-ai/dotprompt

جديد:

npm i genkit

القديم:

import { … } from '@genkit-ai/ai';
import { … } from '@genkit-ai/core';
import { … } from '@genkit-ai/flow';
import * as z from 'zod';

جديد:

import { genkit, z } from 'genkit';

لا يزال يجب تثبيت وتصدير مكوّنات Genkit الإضافية بشكلٍ فردي.

3- ضبط Genkit

في السابق، كان يتمّ إعداد Genkit مرّة واحدة على مستوى النظام من خلال استدعاء الدالة configureGenkit. سيتم ربط جميع موارد Genkit (عمليات التنقّل والأدوات والطلبات وما إلى ذلك) تلقائيًا بهذه الإعدادات الشاملة.

توفّر أداة Genkit 0.9 مثيلات Genkit، يضمّ كلّ منها إعدادًا. راجِع الأمثلة التالية:

القديم:

import { configureGenkit } from '@genkit-ai/core';

configureGenkit({
  telemetry: {
    instrumentation: ...,
    logger: ...
  }
});

جديد:

import { genkit } from 'genkit';
import { logger } from 'genkit/logging';
import { enableFirebaseTelemetry } from '@genkit-ai/firebase';

logger.setLogLevel('debug');
enableFirebaseTelemetry({...});

const ai = genkit({ ... });

لنحلّل هذه العوامل:

• تم استبدال configureGenkit() بـ genkit()، ويعرض مثيلًا من Genkit تم ضبطه بدلاً من ضبط الإعدادات بشكل عام.
• أصبحت دالة إعداد Genkit متوفّرة الآن في حزمة genkit.
• لا يزال يتم ضبط التسجيل والإحصاءات على مستوى النظام باستخدام طرقها الصريحة. تنطبق هذه الإعدادات بشكلٍ موحّد على جميع مثيلات Genkit.

4. تحديد مسارات البيانات وبدء خادم مسارات البيانات بشكل صريح

بعد أن أصبح لديك مثيل Genkit تم ضبطه، عليك تحديد عمليات النقل. يتم الآن استدعاء جميع طرق واجهة برمجة التطبيقات الأساسية الموجّهة للمطوّرين، مثل defineFlow وdefineTool وonFlow، من خلال هذه النسخة.

يختلف ذلك عن الطريقة السابقة التي تم فيها تسجيل عمليات التنقّل والأدوات على مستوى العالم.

القديم:

import { defineFlow, defineTool, onFlow } from '@genkit-ai/core';

defineFlow(...);
defineTool(...);

onFlow(...);

جديد:

// Define tools and flows
const sampleFlow = ai.defineFlow(...);
const sampleTool = ai.defineTool(...);

// onFlow now takes the Genkit instance as first argument
// This registers the flow as a callable firebase function
onFlow(ai, ...);  

const flows = [ sampleFlow, ... ];
// Start the flow server to make the registered flows callable over HTTP
ai.startFlowServer({flows});

اعتبارًا من الآن، يجب تسجيل جميع مسارات الإحالات الناجحة التي تريد إتاحتها بشكل صريح في صفيف flows أعلاه.

5- يجب أن تكون الأدوات والطلبات محدّدة بشكل ثابت.

في الإصدارات السابقة من Genkit، كان بإمكانك تحديد الأدوات والطلبات بشكل ديناميكي أثناء التشغيل مباشرةً من داخل مسار.

في الإصدار 0.9 من Genkit، لم يعُد هذا السلوك مسموحًا به. بدلاً من ذلك، عليك تحديد جميع الإجراءات ومسارات الإحالات الناجحة خارج نطاق تنفيذ مسار الإحالة الناجحة (أي بشكل ثابت).

يفرض هذا التغيير فصلاً أكثر صرامة بين تعريفات الإجراءات وتنفيذها.

إذا تمّ تحديد أيّ من الرموز البرمجية ديناميكيًا، يجب إعادة تنظيمها. بخلاف ذلك، سيتم طرح خطأ أثناء التشغيل عند تنفيذ العملية.

❌ الإجراءات غير المسموح بها:

const flow = defineFlow({...}, async (input) => {
  const tool = defineTool({...});
  await tool(...);
});

✅ يُرجى اتّباع الخطوات التالية:

const tool = ai.defineTool({...});

const flow = ai.defineFlow({...}, async (input) => {
  await tool(...);
});

6- واجهة برمجة تطبيقات جديدة لعمليات البث

في الإصدار 0.9 من Genkit، بسّطنا بنية تعريف عملية البث وتنفيذها.

أولاً، تم فصل defineFlow وdefineStreamingFlow. إذا كانت لديك عملية تريد بثّها، عليك تعديل الرمز لتحديدها من خلال defineStreamingFlow.

ثانيًا، بدلاً من استدعاء دالتَي stream() وresponse() المنفصلتَين، أصبح كلّ من stream وresponse الآن قيمتَين يتم عرضهما مباشرةً من عملية المعالجة. ويؤدي هذا التغيير إلى تبسيط بث المحتوى.

القديم:

import { defineFlow, streamFlow } from '@genkit-ai/flow';

const myStreamingFlow = defineFlow(...);
const { stream, output } = await streamFlow(myStreamingFlow, ...);

for await (const chunk of stream()) {
  console.log(chunk);
}

console.log(await output());

جديد:

const myStreamingFlow = ai.defineStreamingFlow(...);
const { stream, response } = await myStreamingFlow(...);

for await (const chunk of stream) {
  console.log(chunk);
}

console.log(await response);

7- استبدال طرق فئة GenerateResponse بخصائص الحصول

في السابق، كنت تحصل على الإخراج أو النص المهيكل للردّ باستخدام طرق الفئة، مثل output() أو text().

في الإصدار 0.9 من Genkit، تم استبدال هذه الطرق بسمات الحصول على البيانات. ويسهّل ذلك التعامل مع الردود.

القديم:

const response = await generate({ prompt: 'hi' });
console.log(response.text());

جديد:

const response = await ai.generate('hi');
console.log(response.text);

وينطبق الأمر نفسه على output:

القديم:

console.log(response.output());

جديد:

console.log(response.output);

8- إيقاف إنشاء الاقتراحات

تعمل أداة Genkit 0.9 على تبسيط معالجة الردود من خلال إزالة سمة candidates. في السابق، كان بإمكان الردود أن تحتوي على عدة مرشّحين، وكان عليك التعامل معها بشكل صريح. الآن، يتم عرض المرشح الأول فقط مباشرةً في ردّ بسيط.

ولن يعمل بعد ذلك أي رمز يصل إلى المرشحين مباشرةً.

القديم:

const response = await generate({
 messages: [ { role: 'user', content: ...} ]
});
console.log(response.candidates); // previously you could access candidates directly

جديد:

const response = await ai.generate({
 messages: [ { role: 'user', content: ...} ]
});
console.log(response.message); // single candidate is returned directly in a flat response

9- واجهة برمجة التطبيقات لميزة "إنشاء" - تحسينات "المحادثات المتعدّدة"

بالنسبة إلى المحادثات التي تتضمّن عدّة أدوار، تم استبدال الطريقة القديمة toHistory() بـ messages، ما يبسّط بشكل أكبر طريقة التعامل مع سجلّ المحادثات.

القديم:

const history = response.toHistory();

جديد:

const response = await ai.generate({
 messages: [ { role: 'user', content: ...} ]
});
const history = response.messages;

10- Streamlined Chat API

في الإصدار 0.9 من Genkit، تمت إعادة تصميم Chat API لتسهيل إدارة الجلسات والتفاعل. في ما يلي كيفية الاستفادة من هذه الميزة في كلّ من تجارب المحادثة المتزامنة والمحادثة المباشرة:

import { genkit } from 'genkit';
import { gemini15Flash, googleAI } from '@genkit-ai/googleai';

const ai = genkit({
 plugins: [googleAI()],
 model: gemini15Flash,
});

const session = ai.createSession({ store: firestoreSessionStore() });
const chat = await session.chat({ system: 'talk like a pirate' });

let response = await chat.send('hi, my name is Pavel');
console.log(response.text()); // "hi Pavel, I'm llm"

// continue the conversation
response = await chat.send("what's my name");
console.log(response.text()); // "Pavel"

// can stream
const { response, stream } = await chat.sendStream('bye');
for await (const chunk of stream) {
 console.log(chunk.text());
}
console.log((await response).text());

// can load session from the store
const prevSession = await ai.loadSession(session.id, { store });
const prevChat = await prevSession.chat();
await prevChat.send('bye');