نقطة
الكتابات/tutorial/2026/06
● Tutorial1 يونيو 2026·30 دقيقة

Google Genkit 1.0: بناء تدفقات وعملاء ذكاء اصطناعي احترافية مع Next.js

تعلّم كيف تبني تطبيقات ذكاء اصطناعي جاهزة للإنتاج باستخدام Google Genkit 1.0 مع Next.js وTypeScript. يغطي هذا الدليل التدفقات المكتوبة، والأدوات المخصصة، والـ Middleware، والبث المباشر، والنشر.

AI Bot
AI Bot
Author
·EN · FR · AR

المتطلبات الأساسية

قبل البدء، تأكد من توفر ما يلي:

  • Node.js الإصدار 20 أو أحدث
  • مشروع Next.js 15 (أو أنشئ مشروعاً جديداً باستخدام create-next-app)
  • مفتاح Google AI API من Google AI Studio
  • معرفة أساسية بـ TypeScript
  • إلمام بـ Next.js App Router

ما الذي ستبنيه؟

في هذا الدليل، ستنشئ واجهة برمجية لمساعد محتوى ذكي مدعوم بـ Google Genkit 1.0. سيتضمن التطبيق:

  • تدفقات مكتوبة (Typed Flows) — سير عمل قابلة للتركيب مع التحقق من المدخلات والمخرجات
  • أدوات مخصصة (Custom Tools) — دوال يستطيع الذكاء الاصطناعي استدعاؤها لجلب بيانات حقيقية
  • طبقة Middleware — منطق إعادة المحاولة، والانتقال التلقائي بين النماذج، واعتراض الطلبات
  • البث المباشر — استجابات فورية لتجربة مستخدم أفضل
  • مسارات API في Next.js — نقاط نهاية جاهزة للإنتاج باستخدام @genkit-ai/next

ما هو Google Genkit؟

Google Genkit هو إطار عمل TypeScript مفتوح المصدر من Firebase لبناء تطبيقات مدعومة بالذكاء الاصطناعي. وصل إلى الإصدار المستقر 1.0 أواخر عام 2024، وتوسّع بسرعة خلال 2025–2026، ليشمل:

  • واجهة موحدة للنماذج من Google وOpenAI وAnthropic وOllama وغيرها
  • دعم متكامل للتدفقات وخطوط RAG والعملاء المستقلين
  • نظام Middleware قابل للتركيب (أُعلن في مايو 2026) لتعزيز موثوقية خطوط الذكاء الاصطناعي
  • واجهة مطوّر تفاعلية لاختبار التدفقات وفحص التتبعات
  • حزم SDK رسمية لـ Next.js وAngular والمنصات المحمولة

الخطوة 1: إعداد المشروع

إذا لم يكن لديك مشروع Next.js، أنشئ واحداً:

npx create-next-app@latest genkit-demo --typescript --tailwind --app
cd genkit-demo

ثم ثبّت Genkit والإضافات اللازمة:

npm install genkit @genkit-ai/google-genai @genkit-ai/next @genkit-ai/middleware
npm install -D genkit-cli

أضف مفتاح API في ملف .env.local:

GOOGLE_GENAI_API_KEY=your_api_key_here

لا تُدرج ملف .env.local في نظام إدارة النسخ. تأكد من إضافته إلى .gitignore.

الخطوة 2: تهيئة Genkit

أنشئ نسخة Genkit مشتركة تُستخدم في جميع التدفقات. أنشئ الملف lib/genkit.ts:

import { genkit } from 'genkit';
import { googleAI } from '@genkit-ai/google-genai';
 
export const ai = genkit({
  plugins: [
    googleAI({
      apiKey: process.env.GOOGLE_GENAI_API_KEY,
    }),
  ],
  model: 'googleai/gemini-2.5-flash',
});

هذا ينشئ نسخة واحدة من ai مهيّأة بإضافة Google AI. تُحدد خاصية model النموذج الافتراضي لجميع استدعاءات ai.generate() التي لا تحدد نموذجاً صريحاً.

يمكنك التبديل إلى أي مزوّد نماذج مدعوم — مثل @genkit-ai/openai أو @genkit-ai/anthropic — بتغيير الإضافة والاسم فقط، بينما يبقى كود التدفقات دون تعديل.

الخطوة 3: تعريف أول تدفق

التدفقات هي دوال مكتوبة تُلفّ منطق الذكاء الاصطناعي مع دعم المراقبة والتحقق من الأنواع والبث. أنشئ lib/flows/summarize.ts:

import { z } from 'genkit';
import { ai } from '../genkit';
 
export const summarizeFlow = ai.defineFlow(
  {
    name: 'summarize',
    inputSchema: z.object({
      text: z.string().min(1).describe('النص المراد تلخيصه'),
      maxWords: z.number().optional().default(150),
    }),
    outputSchema: z.object({
      summary: z.string(),
      keyPoints: z.array(z.string()),
    }),
  },
  async (input) => {
    const result = await ai.generate({
      prompt: `لخّص النص التالي في ما لا يزيد عن ${input.maxWords} كلمة.
أعد كائن JSON يحتوي على:
- summary: فقرة موجزة
- keyPoints: مصفوفة من 3 إلى 5 نقاط رئيسية
 
النص: ${input.text}`,
      output: {
        schema: z.object({
          summary: z.string(),
          keyPoints: z.array(z.string()),
        }),
      },
    });
 
    return result.output!;
  }
);

نقاط جوهرية:

  • تستخدم inputSchema وoutputSchema مكتبة Zod لاستنتاج أنواع TypeScript تلقائياً
  • التدفق مستقل بذاته وسهل الاختبار في عزل تام
  • يتتبع Genkit تلقائياً كل استدعاء لـ ai.generate() داخل التدفق

الخطوة 4: إنشاء أدوات مخصصة

تسمح الأدوات للذكاء الاصطناعي باستدعاء دوال خارجية كواجهات REST أو قواعد البيانات. يقرر النموذج متى يستدعي الأداة بناءً على وصفها، ويتولى Genkit حلقة التنفيذ تلقائياً.

أنشئ lib/tools/weather.ts:

import { z } from 'genkit';
import { ai } from '../genkit';
 
export const weatherTool = ai.defineTool(
  {
    name: 'getWeather',
    description: 'يجلب حالة الطقس الحالية لمدينة معينة',
    inputSchema: z.object({
      city: z.string().describe('اسم المدينة'),
    }),
    outputSchema: z.object({
      temperature: z.number().describe('درجة الحرارة بالسيليزيوس'),
      condition: z.string().describe('وصف حالة الطقس'),
      humidity: z.number().describe('نسبة الرطوبة المئوية'),
    }),
  },
  async ({ city }) => {
    const response = await fetch(
      `https://wttr.in/${encodeURIComponent(city)}?format=j1`
    );
    const data = await response.json();
    const current = data.current_condition[0];
    return {
      temperature: parseInt(current.temp_C),
      condition: current.weatherDesc[0].value,
      humidity: parseInt(current.humidity),
    };
  }
);

أنشئ تدفقاً يستخدم هذه الأداة في lib/flows/weather-agent.ts:

import { z } from 'genkit';
import { ai } from '../genkit';
import { weatherTool } from '../tools/weather';
 
export const weatherAgentFlow = ai.defineFlow(
  {
    name: 'weatherAgent',
    inputSchema: z.object({
      query: z.string().describe('سؤال عن الطقس بلغة طبيعية'),
    }),
    outputSchema: z.string(),
  },
  async (input) => {
    const result = await ai.generate({
      prompt: input.query,
      tools: [weatherTool],
    });
    return result.text;
  }
);

عند تشغيل هذا التدفق، يتولى Genkit حلقة استدعاء الأدوات بالكامل: يطلب النموذج بيانات الطقس، ينفّذ Genkit الأداة، ثم يُعيد النتيجة إلى النموذج حتى يُنتج إجابة نهائية.

الخطوة 5: إضافة Middleware

توفر حزمة @genkit-ai/middleware (المُعلَن عنها في مايو 2026) طبقة اعتراض قابلة للتركيب حول خطوط الذكاء الاصطناعي. تدعم ثلاثة أنواع من الخطافات:

  • خطافات التوليد (generate hooks) — منطق على مستوى المحادثة
  • خطافات النموذج (model hooks) — إعادة المحاولة والانتقال لكل استدعاء نموذج
  • خطافات الأدوات (tool hooks) — الموافقة والحماية قبل تنفيذ الأدوات

حدّث lib/genkit.ts لإضافة منطق إعادة المحاولة والانتقال التلقائي والتسجيل:

import { genkit } from 'genkit';
import { googleAI } from '@genkit-ai/google-genai';
import { withRetry, withFallback, withLogging } from '@genkit-ai/middleware';
 
export const ai = genkit({
  plugins: [
    googleAI({ apiKey: process.env.GOOGLE_GENAI_API_KEY }),
  ],
  model: 'googleai/gemini-2.5-flash',
  middleware: [
    withLogging({ logLevel: 'info' }),
    withRetry({
      maxAttempts: 3,
      backoff: 'exponential',
      initialDelayMs: 500,
    }),
    withFallback({
      fallbackModel: 'googleai/gemini-flash-latest',
      onError: (error) => error.code === 'QUOTA_EXCEEDED',
    }),
  ],
});

هذا الإعداد يمنحك:

  1. سجلات منظمة لكل طلب واستجابة من الذكاء الاصطناعي
  2. ما يصل إلى 3 إعادات محاولة تلقائية مع تأخير تصاعدي
  3. تبديل شفاف للنموذج إلى gemini-flash-latest عند تجاوز حصة الاستخدام

الخطوة 6: دمج مسارات API في Next.js

توفر حزمة @genkit-ai/next الدالة appRoute التي تُلفّ تدفق Genkit كمعالج لـ Next.js App Router بدون أي كود إضافي.

أنشئ app/api/summarize/route.ts:

import { appRoute } from '@genkit-ai/next';
import { summarizeFlow } from '@/lib/flows/summarize';
 
export const POST = appRoute(summarizeFlow);

أنشئ app/api/weather/route.ts:

import { appRoute } from '@genkit-ai/next';
import { weatherAgentFlow } from '@/lib/flows/weather-agent';
 
export const POST = appRoute(weatherAgentFlow);

المعالج appRoute يتولى تلقائياً:

  • تحليل وتحقق جسم طلب JSON وفق inputSchema
  • إعادة JSON صحيح مطابق لـ outputSchema
  • بث الاستجابات عند استخدام التدفق لـ streamingCallback
  • إعادة استجابات HTTP مناسبة عند فشل التحقق

اختبر نقطة النهاية باستخدام curl:

curl -X POST http://localhost:3000/api/summarize \
  -H "Content-Type: application/json" \
  -d '{
    "text": "الذكاء الاصطناعي يُحوّل تطوير البرمجيات بوتيرة غير مسبوقة...",
    "maxWords": 80
  }'

الخطوة 7: البث المباشر للاستجابات

للتدفقات الطويلة أو التفاعلات الشبيهة بالمحادثة، يمكنك بث المخرجات إلى العميل لحظةً بلحظة. أنشئ lib/flows/stream-chat.ts:

import { z } from 'genkit';
import { ai } from '../genkit';
 
export const streamChatFlow = ai.defineFlow(
  {
    name: 'streamChat',
    inputSchema: z.object({
      message: z.string().describe('رسالة المستخدم'),
    }),
    outputSchema: z.string(),
    streamSchema: z.string(),
  },
  async (input, streamingCallback) => {
    const result = await ai.generate({
      prompt: input.message,
      onChunk: (chunk) => {
        if (streamingCallback && chunk.text) {
          streamingCallback(chunk.text);
        }
      },
    });
    return result.text;
  }
);

أنشئ app/api/chat/route.ts:

import { appRoute } from '@genkit-ai/next';
import { streamChatFlow } from '@/lib/flows/stream-chat';
 
export const POST = appRoute(streamChatFlow, { streaming: true });

على جانب العميل، استهلك البث:

async function streamChat(message: string, onChunk: (text: string) => void) {
  const response = await fetch('/api/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message }),
  });
 
  const reader = response.body?.getReader();
  const decoder = new TextDecoder();
 
  while (reader) {
    const { done, value } = await reader.read();
    if (done) break;
    onChunk(decoder.decode(value, { stream: true }));
  }
}

الخطوة 8: واجهة المطوّر وتتبع التنفيذ

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

افتح نافذة طرفية ثانية بجوار عملية npm run dev:

npx genkit start -- npx tsx --watch lib/genkit.ts

تفتح واجهة المطوّر على http://localhost:4000 وتوفر:

  • Flow Runner — تشغيل أي تدفق مسجّل بمدخلات مخصصة
  • Model Playground — إرسال مطالبات مباشرة لأي نموذج مهيّأ
  • Trace Explorer — فحص كل استدعاء generate() مع المدخلات والمخرجات وزمن الاستجابة وعدد الرموز
  • Tool Inspector — اختبار مخططات الأدوات وتزوير استجاباتها

استخدم Trace Explorer أثناء التطوير لفهم استهلاك الرموز لكل تدفق. يساعدك هذا على تحسين المطالبات قبل النشر حيث تكون التكاليف حقيقية.

الخطوة 9: النشر في بيئة الإنتاج

Vercel

أضف متغير البيئة في إعدادات مشروع Vercel:

GOOGLE_GENAI_API_KEY=your_production_key

ثم انشر بشكل عادي:

npx vercel --prod

Firebase App Hosting أو Cloud Run

للتكامل العميق مع المراقبة، أضف إضافة Firebase:

import { firebaseApp } from '@genkit-ai/firebase';
 
export const ai = genkit({
  plugins: [
    googleAI({ apiKey: process.env.GOOGLE_GENAI_API_KEY }),
    firebaseApp(),
  ],
});

ترسل إضافة Firebase التتبعات تلقائياً إلى Cloud Logging وتفعّل لوحة مراقبة الإنتاج في وحدة تحكم Firebase.

اختبار التطبيق

تدفقات Genkit هي دوال غير متزامنة عادية، مما يجعل اختبارها سهلاً. أنشئ __tests__/summarize.test.ts:

import { describe, it, expect } from 'vitest';
import { summarizeFlow } from '@/lib/flows/summarize';
 
describe('summarizeFlow', () => {
  it('يُعيد ملخصاً ونقاطاً رئيسية', async () => {
    const result = await summarizeFlow({
      text: 'يُحوّل الذكاء الاصطناعي كل قطاع من الرعاية الصحية إلى المالية.',
      maxWords: 50,
    });
 
    expect(result.summary).toBeTruthy();
    expect(result.keyPoints).toBeInstanceOf(Array);
    expect(result.keyPoints.length).toBeGreaterThanOrEqual(1);
  });
});

استكشاف الأخطاء وإصلاحها

GOOGLE_GENAI_API_KEY غير موجود عند التشغيل

تأكد من ضبط المفتاح في .env.local للتطوير المحلي. على Vercel، تحقق من قسم Environment Variables في إعدادات المشروع.

مخرجات التدفق لا تطابق المخطط

فعّل output.strict: true في ai.generate() لرمي خطأ عند إعادة النموذج لـ JSON غير صحيح. أضف تلميحات .describe() إلى حقول Zod.

حلقة استدعاء الأدوات لا تنتهي

حدد maxTurns في استدعاء ai.generate() للتحكم في عدد تكرارات استدعاء الأدوات:

const result = await ai.generate({
  prompt: input.query,
  tools: [weatherTool],
  maxTurns: 5,
});

الخطوات التالية

بعد إعداد Genkit بنجاح، يمكنك توسيع تطبيقك في عدة اتجاهات:

  • خطوط RAG — استخدم ai.defineRetriever مع Pinecone أو Cloud Firestore لإضافة بحث مستند إلى المستندات
  • عملاء متعددو الخطوات — سلسل التدفقات معاً لمهام استدلال معقدة
  • التقييم — استخدم @genkit-ai/evaluation لتقييم مخرجات التدفقات تلقائياً
  • إدارة المطالبات — خزّن المطالبات الموثّقة في Firestore باستخدام ai.definePrompt

خلاصة

يوفر Google Genkit 1.0 أساساً متيناً وجاهزاً للإنتاج لبناء تطبيقات مدعومة بالذكاء الاصطناعي بـ TypeScript. يجعل مزيجه من التدفقات المكتوبة ونظام Middleware القابل للتركيب والتكامل الأصلي مع Next.js منه أحد أعملي أطر الذكاء الاصطناعي المتاحة لمطوري JavaScript اليوم. سواء كنت تبني نقطة نهاية بسيطة للتلخيص أو عميلاً متعدد الخطوات مع استدعاء الأدوات، يمنحك Genkit قابلية المراقبة والبنية اللازمتين للشحن بثقة والتكرار بسرعة.