1. مقدمة
في هذا الدرس التطبيقي حول الترميز، سننشئ GlowUp، وهي أداة لاستعادة الصور. يستخدم GlowUp الذكاء الاصطناعي لاستعادة الصور القديمة أو التالفة أو الصور بالأسود والأبيض، وإنشاء صور ملوّنة عالية الجودة بدقة 4K. يمكنك استخدام هذه الأداة لإضفاء الحيوية على صورك العائلية، أو حتى تكييفها لاستعادة الرسوم التوضيحية أو الرسومات أو اللوحات أو غيرها من أشكال الصور التالفة.
ستستخدم Genkit Go لتنفيذ منطق التطبيق وGemini 3 Pro Image (المعروف أيضًا باسم Nano Banana Pro) كنموذج لمعالجة الصور.
المتطلبات الأساسية
- معرفة أساسية بلغة Go البرمجية
- معرفة أساسية بوحدة تحكّم Google Cloud
أهداف الدورة التعليمية
- كيفية تطوير تطبيقات Genkit في Go
- مفاهيم Genkit الأساسية، مثل المسارات والمكوّنات الإضافية والطلبات
- كيفية كتابة الطلبات باستخدام نماذج Handlebars
- كيفية الحصول على بيانات الصور من ردود النموذج
المتطلبات
يمكن إجراء ورشة العمل هذه بالكامل ضمن Google Cloud Shell، الذي يتضمّن جميع التبعيات اللازمة (gcloud CLI وأداة تعديل الرموز وGo وGemini CLI) المثبّتة مسبقًا.
بدلاً من ذلك، إذا كنت تفضّل العمل على جهازك الخاص، ستحتاج إلى ما يلي:
- سلسلة أدوات Go (الإصدار 1.24 أو إصدار أحدث)
- Node.js v20 أو إصدار أحدث (لواجهة سطر الأوامر في
genkit) - جهاز طرفي مثبَّت عليه واجهة سطر الأوامر (CLI) لـ
gcloud - بيئة تطوير متكاملة (IDE) لتعديل الرمز، مثل VS Code أو ما شابه
- ننصح باستخدام: وكيل ترميز مثل Gemini CLI أو Antigravity
التكنولوجيات الرئيسية
في ما يلي مزيد من المعلومات حول التكنولوجيات التي سنستخدمها:
- Gemini Nano Banana Pro (Gemini 3 Pro Image): النموذج الذي يستند إليه خيار الاستعادة
- Genkit Go: مجموعة أدواتنا لتنظيم طلبات النماذج
2. إعداد البيئة
يمكنك تشغيل هذا التمرين من جهازك أو من السحابة الإلكترونية بالكامل. حتى إذا قرّرت تشغيل الرمز على جهازك، ستحتاج إلى مشروع على Google Cloud لنشر مكوّنات جهة الخادم على السحابة الإلكترونية. اتّبِع الخطوات الواردة في القسم التالي لإنشائه.
إعداد بيئة ذاتية التعلّم
- سجِّل الدخول إلى Google Cloud Console وأنشئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. إذا لم يكن لديك حساب على Gmail أو Google Workspace، عليك إنشاء حساب.



- اسم المشروع هو الاسم المعروض للمشاركين في هذا المشروع. وهي سلسلة أحرف لا تستخدمها Google APIs. ويمكنك تعديلها في أي وقت.
- رقم تعريف المشروع فريد في جميع مشاريع Google Cloud وغير قابل للتغيير (لا يمكن تغييره بعد ضبطه). تنشئ Cloud Console تلقائيًا سلسلة فريدة، وعادةً لا يهمّك ما هي. في معظم الدروس التطبيقية حول الترميز، ستحتاج إلى الإشارة إلى رقم تعريف المشروع (يتم تحديده عادةً على أنّه
PROJECT_ID). إذا لم يعجبك رقم التعريف الذي تم إنشاؤه تلقائيًا، يمكنك إنشاء رقم تعريف عشوائي آخر. يمكنك بدلاً من ذلك تجربة اسم من اختيارك والتحقّق من توفّره. ولا يمكن تغييره بعد هذه الخطوة ويظل ساريًا طوال مدة المشروع. - للعلم، هناك قيمة ثالثة، وهي رقم المشروع، تستخدمها بعض واجهات برمجة التطبيقات. يمكنك الاطّلاع على مزيد من المعلومات عن هذه القيم الثلاث في المستندات.
- بعد ذلك، عليك تفعيل الفوترة في Cloud Console لاستخدام موارد/واجهات برمجة تطبيقات Cloud. لن يتطلّب تنفيذ هذا الدرس التطبيقي حول الترميز تكلفة كبيرة، هذا إن تطلّب أي تكلفة على الإطلاق. لإيقاف الموارد لتجنُّب تحمُّل تكاليف الفوترة بعد هذا البرنامج التعليمي، يمكنك حذف الموارد التي أنشأتها أو حذف المشروع. يمكن لمستخدمي Google Cloud الجدد الاستفادة من برنامج الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.
بدء Cloud Shell
على الرغم من إمكانية تشغيل Google Cloud عن بُعد من الكمبيوتر المحمول، ستستخدم في هذا الدرس التطبيقي حول الترميز Google Cloud Shell، وهي بيئة سطر أوامر تعمل في السحابة الإلكترونية.
من Google Cloud Console، انقر على رمز Cloud Shell في شريط الأدوات في أعلى يسار الصفحة:

من المفترض أن يستغرق توفير البيئة والاتصال بها بضع ثوانٍ فقط. عند الانتهاء، من المفترض أن يظهر لك شيء مثل هذا:

يتم تحميل هذا الجهاز الافتراضي بجميع أدوات المطوّرين التي ستحتاج إليها. وتوفّر هذه الأداة دليلاً رئيسيًا دائمًا بسعة 5 غيغابايت، وتعمل على Google Cloud، ما يحسّن أداء الشبكة والمصادقة بشكل كبير. يمكن تنفيذ جميع أعمالك في هذا الدرس التطبيقي حول الترميز من خلال المتصفّح. ولست بحاجة إلى تثبيت أي شيء.
3- إعداد المشروع
إنشاء المشروع
أولاً، علينا إنشاء دليل جديد لمشروعك وبدء تهيئة وحدة Go. في الوحدة الطرفية، نفِّذ الأوامر التالية:
mkdir -p glowup && cd glowup
go mod init glowup
تثبيت Genkit CLI
علينا الآن تثبيت Genkit CLI. يتيح لك ذلك الوصول إلى أدوات المطوّرين المحلية، بما في ذلك واجهة مستخدم المطوّر. في نافذة المحطة الطرفية، اكتب:
curl -sL cli.genkit.dev | bash
ضبط متغيرات البيئة
تأكَّد من إعداد بيانات اعتماد Google Cloud الصحيحة. يجب أن يكون الموقع الجغرافي global عند استخدام نماذج Gemini 3 Pro Preview (ومن بينها Nano Banana Pro).
export GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
export GOOGLE_CLOUD_LOCATION=global
نفِّذ الأمر التالي في وضع shell لتفعيل واجهة برمجة التطبيقات Vertex AI API للمشروع الحالي:
gcloud services enable aiplatform.googleapis.com
وإذا كنت تشغّل من جهازك المحلي (وليس على CloudShell)، عليك المصادقة باستخدام الأمر gcloud:
gcloud auth application-default login
4. إنشاء أول تطبيق Genkit
Genkit هو إطار عمل مفتوح المصدر مصمَّم لمساعدة المطوّرين في إنشاء تطبيقات مستندة إلى الذكاء الاصطناعي وجاهزة للإنتاج ونشرها ومراقبتها. في هذا القسم، سننشئ تطبيقًا بسيطًا باسم "Hello World" لمساعدتك في التعرّف على إطار العمل قبل التعمّق في منطق استعادة الصور.
مصطلحات Genkit
قبل بدء العمل باستخدام Genkit، من المهم فهم بعض المصطلحات الأساسية:
- المكوّنات الإضافية: تُستخدَم لتوسيع إمكانات Genkit. من بين أمور أخرى، يمكنك من خلال الإضافات تسجيل نماذج الذكاء الاصطناعي لتشغيل تطبيقك.
- التدفقات: المكوّن الأساسي لبنية Genkit يأخذ التدفق النموذجي مدخلات ويعالجها ويعرض مخرجات. لا يتطلّب بالضرورة استخدام نموذج، ولكن في معظم الأحيان ستستخدم نماذج داخل التدفقات.
- الطلبات: نماذج تفاعل مخزّنة بتنسيق dotprompt (محفوظة كملفات
*.prompt). لا تحتوي هذه الملفات على تعليمات النموذج فحسب، بل تحتوي أيضًا على إعدادات مثل اسم النموذج ومعلَماته ومدخلاته ومخرجاته.
التواصل مع نماذج الذكاء الاصطناعي
يستخدم Genkit المكوّنات الإضافية لربط الرمز البرمجي بمقدّمي النماذج. تتوفّر مكوّنات إضافية لجميع مقدّمي النماذج الرئيسية، بما في ذلك Google وAnthropic وOpenAI. ويمكنك أيضًا استخدام المكوّنات الإضافية للربط بالنماذج المحلية (مثل استخدام Ollama) أو لتوسيع إمكانات Genkit (مثل الربط بخوادم MCP).
للوصول إلى نماذج Google، يجب استخدام المكوّن الإضافي googlegenai. وهي تتيح استخدام واجهتَين خلفيتَين:
- Google AI: الأفضل لإنشاء النماذج الأولية. يستخدم مفتاح واجهة برمجة التطبيقات.
- Vertex AI (Google Cloud): يُنصح به للاستخدام في مرحلة الإنتاج. يستخدم رقم تعريف المشروع والموقع الجغرافي.
في هذا الدرس التطبيقي حول الترميز، سنستخدم مصادقة Vertex AI للإشارة إلى المشروع الذي أنشأته في بداية الدرس التطبيقي.
إنشاء مسار ترحيبي
قبل التعمّق في مسار استعادة الصور في Glow Up، لننشئ مسارًا أساسيًا للتعرّف على المفاهيم والتأكّد من أنّ الإعدادات تعمل بشكل صحيح.
التدفق هو دالة Genkit خاصة تغلّف منطق الذكاء الاصطناعي لتوفير ما يلي:
- المدخلات والمخرجات الآمنة من حيث النوع: يمكنك تحديد المخططات باستخدام بُنى Go للتحقّق من صحة البيانات الثابتة وأثناء التشغيل
- إتاحة البث: بث الردود الجزئية أو البيانات المخصّصة
- دمج واجهة المستخدم للمطوّرين: يمكنك اختبار عمليات سير العمل وتصحيح أخطائها باستخدام عمليات التتبُّع المرئية
- سهولة النشر: يمكنك نشر النماذج كنقاط نهاية HTTP على أي نظام أساسي
افتح بيئة التطوير المتكاملة (IDE) وأنشئ ملف main.go في دليل مشروعك. في حال استخدام Cloud Shell، يمكنك استخدام الأمر التالي:
cloudshell edit main.go
بعد ذلك، أضِف الرمز التالي:
main.go
package main
import (
"context"
"log"
"os"
"os/signal"
"syscall"
"github.com/firebase/genkit/go/genkit"
"github.com/firebase/genkit/go/ai"
"github.com/firebase/genkit/go/plugins/googlegenai"
)
func main() {
ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer cancel()
// Initialize Genkit with the Vertex AI plugin
g := genkit.Init(ctx,
genkit.WithPlugins(&googlegenai.VertexAI{}),
)
// Define the greeter flow
genkit.DefineFlow(g, "greeter", func(ctx context.Context, name string) (string, error) {
text, err := genkit.GenerateText(ctx, g,
ai.WithModelName("vertexai/gemini-2.5-pro"),
ai.WithPrompt("Say a warm and creative hello to %s", name),
)
if err != nil {
return "", err
}
return text, nil
})
// Register the flow here in the next steps
log.Println("GlowUp initialized. Ready for flows.")
<-ctx.Done()
}
احفظ الملف ثم شغِّل الأمر go mod tidy لتعديل التبعيات:
go mod tidy
يُهيئ الرمز أعلاه Genkit باستخدام المكوّن الإضافي VertexAI، ويحدّد سير عمل باسم "greeter"، ثم ينتظر إلى الأبد على <-ctx.Done(). نحن نوقف التنفيذ مؤقتًا حتى لا ينتهي هذا البرنامج على الفور، لأنّنا لا نقدّم له أي تعليمات لتنفيذ المسار فعليًا.
هذا يعني أنّه إذا شغّلنا هذا البرنامج كما هو الآن، لن يؤدي الكثير من المهام بمفرده، بل علينا استدعاء المسار بطريقة ما. في تطبيق إنتاج حقيقي، سنقوم بتضمين هذا التدفق في خادم ويب أو تطبيق CLI، ولكن أثناء مرحلة التطوير، يمكننا استخدام واجهة سطر الأوامر genkit لمساعدتنا في تطوير التدفق وتحسينه.
تم تطوير واجهة سطر الأوامر (CLI) في genkit لمساعدتنا في اختبار النماذج والطلبات والمسارات والمكوّنات الأخرى في حزمة Genkit. كما أنّه يوفّر دعمًا كاملاً لعمليات التتبُّع، وهو أمر مفيد جدًا عندما تريد فهم طريقة عمل التطبيق من الداخل. لتشغيل مسار الترحيب باستخدام واجهة سطر الأوامر في genkit، نفِّذ الأمر التالي:
genkit start -- go run main.go
سيؤدي ذلك إلى تشغيل نقاط نهاية Telemetry API وDeveloper UI. ينبغي أن تظهر لك على النحو التالي:
$ genkit start -- go run main.go Telemetry API running on http://localhost:4033 Project root: /home/daniela/glowup Genkit Developer UI: http://localhost:4000
إذا فتحت localhost:4000 على المتصفّح لتشغيل Dev-UI. من المفترض أن تظهر لك شاشة على النحو التالي:

يمكنك استكشاف واجهة مستخدم المطوّرين على مهل. يمكنك تشغيل مسار "الترحيب" مرة واحدة فقط لمعرفة طريقة عمله.
استخدام نماذج الطلبات
على الرغم من أنّه يمكنك ترميز طلباتك بشكل ثابت في طلبات النموذج كما فعلنا في المثال السابق، فإنّ الطريقة الأفضل هي إنشاء نماذج طلبات لتخزين جميع طلبات تطبيقنا بطريقة مركزية. لا يسهّل ذلك العثور عليها عند إجراء صيانة للرمز البرمجي فحسب، بل يتيح لك أيضًا تجربة الطلبات بشكل مستقل عن المسارات.
لتحديد نماذج الطلبات، تستخدم Genkit تنسيق dotprompt المفتوح المصدر، والذي يتم حفظه كملفات *.prompt. يتألف ملف .prompt من جزأين:
- البيانات التمهيدية: هي مجموعة بيانات بتنسيق YAML تحدّد النموذج ومَعلماته ومخطّطات الإدخال والإخراج
- النص: نص الطلب نفسه، والذي يمكن إنشاؤه باستخدام بنية "handlebars". على سبيل المثال، إذا حدّدت إدخالاً باسم
variable-name، يمكنك الإشارة إليه في النص على النحو التالي:{{variable-name}}.
ستبدو بنية الدليل للمشروع على النحو التالي:
glowup/
├── main.go
└── prompts/
└── greeter.prompt
لنطّلِع على مثال عملي. أولاً، أنشئ المجلد لتخزين الطلبات:
mkdir -p prompts
بعد ذلك، أنشئ ملف greeter.prompt:
cloudshell edit prompts/greeter.prompt
وأدرِج المحتوى التالي:
greeter.prompt

يعرض هذا الطلب بعض ميزات لغة النموذج. أولاً، نحدّد النموذج vertexai/gemini-2.5-flash في البيانات الوصفية. لتحديد نموذج، عليك استخدام التسميات المحدّدة في مستندات المكوّن الإضافي المعنيّ.
يتيح لنا قسم الإعدادات ضبط معلَمات النموذج. نستخدم درجة حرارة 1.9 للسماح للنموذج بأن يكون أكثر إبداعًا. يتراوح مستوى الإبداع بين 0 (نتائج أكثر اتساقًا) و2 (نتائج أكثر إبداعًا). ويتم عادةً نشر هذه المَعلمة وغيرها من مَعلمات النموذج في ورقة النموذج. على سبيل المثال، إليك ورقة النموذج لـ gemini-2.5-flash.
يتيح لنا قسم الإدخال تحديد الوسيطات للطلب. في هذه الحالة، نعرّف الاسم كسلسلة. بعد البيانات الوصفية، لدينا نص الطلب. تحدّد المجموعة الأولى هنا طلب النظام، والمجموعة الثانية هي طلب المستخدم. تتيح كل هذه العناصر معًا استخدام بعض أساليب التلقين الفعّالة للغاية. يمكنك الاطّلاع على المستندات الكاملة حول dotprompt هنا.
الآن، لنعدّل مسار greeter لاستخدام الطلب الذي أنشأناه للتو:
main.go
package main
import (
"context"
"os"
"os/signal"
"syscall"
"github.com/firebase/genkit/go/ai"
"github.com/firebase/genkit/go/genkit"
"github.com/firebase/genkit/go/plugins/googlegenai"
)
func main() {
ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer cancel()
// Initialize Genkit with the Vertex AI plugin
g := genkit.Init(ctx,
genkit.WithPlugins(&googlegenai.VertexAI{}),
genkit.WithDefaultModel("vertexai/gemini-2.5-flash"),
)
// Define the greeter flow
genkit.DefineFlow(g, "greeter", func(ctx context.Context, name *string) (string, error) {
prompt := genkit.LookupPrompt(g, "greeter")
input := map[string]any{
"name": name,
}
resp, err := prompt.Execute(ctx, ai.WithInput(input))
if err != nil {
return "", err
}
return resp.Text(), nil
})
<-ctx.Done()
}
جرِّب تشغيل المسار من سطر الأوامر، مع اسم وبدونه، لمعرفة الفرق. العمل بدون اسم:
genkit flow:run greeter
مثال على الناتج:
$ genkit flow:run greeter Telemetry API running on http://localhost:4035 Running '/flow/greeter' (stream=false)... Result: "Hello there, absolutely delightful human!\n\nThe very moment your message arrived, the day instantly sparkled a little brighter. It's not just nice, it's genuinely **wonderful** to meet you!\n\nMay your entire day be filled with unexpected pockets of joy, effortless triumphs, and all the happiness you truly deserve! We're thrilled to have you here!"
ويمكنك أيضًا إضافة اسم:
genkit flow:run greeter '"Daniela"'
مثال على الناتج:
$ genkit flow:run greeter '"Daniela"' Telemetry API running on http://localhost:4035 Running '/flow/greeter' (stream=false)... Result: "Well hello there, Daniela! What a truly beautiful name, and what an absolute pleasure it is to meet you!\n\nRight from this moment, I just know your day is going to be brimming with positive energy and wonderful surprises. May it be filled with brilliant ideas, joyful moments, and the delightful realization that you're an amazing person doing incredible things. So glad you're here!"
يمكنك ملاحظة أنّ النموذج عمل على النحو المتوقّع. نحن على استعداد للانتقال بهذا المشروع إلى المستوى التالي!
5- استعادة الصور باستخدام Nano Banana Pro
طلب الاستعادة
بعد أن تعرّفت على العناصر الأساسية في Genkit، حان الوقت لإنشاء طلب استعادة الصور.
أنشئ ملفًا باسم glowup.prompt في دليل الطلبات، والصِق فيه المحتوى التالي:
glowup.prompt

يتّبع طلب الاستعادة النمط نفسه الذي يتّبعه طلب "الترحيب"، مع اختلافَين ملحوظَين فقط:
- حجم الصورة: السمة
imageSizeفيimageConfigهي مَعلمة خاصة بنموذج Nano Banana Pro. تتيح لنا هذه الأداة تحديد حجم الناتج على أنّه 1K أو 2K أو 4K. - إدخال الوسائط: نستخدم نموذج
{{ media }}لإدراج الصورة في طلب المستخدم. تتيح لنا هذه التقنية إرسال طلبات متعددة الوسائط إلى النموذج (نص وصورة).
يمكنك اختبار هذا الطلب في واجهة مستخدم المطوّر. يمكنك تعديلها لمعرفة مدى تأثيرها في النتيجة.
مسار استعادة الصور
بعد أن أصبح طلب الاستعادة جاهزًا، لننشئ الآن تطبيق واجهة سطر الأوامر. استبدِل محتوى main.go بالرمز أدناه:
main.go
package main
import (
"context"
"encoding/base64"
"errors"
"flag"
"fmt"
"log"
"mime"
"os"
"os/signal"
"strings"
"syscall"
"github.com/firebase/genkit/go/ai"
"github.com/firebase/genkit/go/genkit"
"github.com/firebase/genkit/go/plugins/googlegenai"
)
func main() {
url := flag.String("url", "", "url of the image to restore")
contentType := flag.String("contentType", "image/jpeg", "content type of the image (default: image/jpeg)")
flag.Parse()
ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer cancel()
// Initialize Genkit with the Vertex AI plugin
g := genkit.Init(ctx,
genkit.WithPlugins(&googlegenai.VertexAI{}),
)
// Input schema for the glowUp flow
type Input struct {
URL string `json:"url,omitempty"`
ContentType string `json:"contentType,omitempty"`
}
glowup := genkit.DefineFlow(g, "glowUp", func(ctx context.Context, input Input) (string, error) {
// 1. Retrieve prompt
prompt := genkit.LookupPrompt(g, "glowup")
if prompt == nil {
return "", errors.New("prompt 'glowup' not found")
}
resp, err := prompt.Execute(ctx, ai.WithInput(input))
if err != nil {
return "", fmt.Errorf("generation failed: %w", err)
}
return resp.Media(), nil
})
// triggers the flow and returns the encoded response from the model
out, err := glowup.Run(ctx, Input{URL: *url, ContentType: *contentType})
if err != nil {
log.Fatalln(err)
}
// decodes image data and returns the appropriate file extension
data, ext, err := decode(out)
if err != nil {
log.Fatalln(err)
}
// writes restored file to disk
filename := "restored" + ext
if err := os.WriteFile(filename, data, 0644); err != nil {
log.Fatalln(err)
}
}
// decode returns the decoded data and the file extension appropriate for the mime type
func decode(text string) ([]byte, string, error) {
if !strings.HasPrefix(text, "data:") {
return nil, "", errors.New("unsupported enconding format")
}
text = strings.TrimPrefix(text, "data:")
parts := strings.Split(text, ";base64,")
mimeType := parts[0]
decoded, err := base64.StdEncoding.DecodeString(parts[1])
if err != nil {
return nil, "", err
}
ext, err := mime.ExtensionsByType(mimeType)
if err != nil {
return nil, "", err
}
return decoded, ext[0], nil
}
يشبه الرمز إلى حد كبير في بنيته مسار greeter، ولكن هذه المرة تم تعديله ليتم تشغيله كتطبيق مستقل لواجهة سطر الأوامر (CLI). بدلاً من حظرها نهائيًا، سيتم تشغيل مسار glowUp وفك ترميز الناتج وحفظ البيانات الثنائية الناتجة على القرص.
نحتاج إلى فك ترميز الناتج لأنّ النموذج يعرض بيانات الصورة بالتنسيق التالي:
data:<mime type>;base64,<base64 encoded image>
يمكنك أن ترى في الدالة decode أننا نستخدم معالجة السلسلة لتقسيم نوع MIME وأجزاء الصورة المرمّزة. بعد ذلك، نستخدم الدالتَين mime.ExtensionByType وbase64.DecodeString لاستخراج المعلومات التي نحتاجها لحفظ الملف.
اختبار عملية الاستعادة
حان الوقت أخيرًا لتشغيل هذا المسار باستخدام صورة حقيقية. إذا لم تكن لديك أي صور قديمة تحتاج إلى بعض الترميم، يمكنك تجربة هذه الصورة من النطاق العام التي تم استردادها من موقع مكتبة الكونغرس الإلكتروني:

إليك الرابط المباشر للصورة لتمريره إلى سير العمل: https://tile.loc.gov/storage-services/service/pnp/fsa/8c01000/8c01700/8c01765v.jpg
export IMAGE_URL="https://tile.loc.gov/storage-services/service/pnp/fsa/8c01000/8c01700/8c01765v.jpg"
go run main.go --url $IMAGE_URL
إليك الصورة التي تم ترميمها وتلوينها:

اكتمال النقل بنجاح
6. نشر glowUp كخدمة ويب
إذا أردت عرض التدفقات في خدمة ويب بدلاً من تطبيق سطر أوامر، يوفّر Genkit طريقة ملائمة لتحويل التدفقات إلى نقاط نهاية باستخدام محوّل genkit.Handler. يسجّل الرمز أدناه سير العمل glowUp كنقطة نهاية glowUp باستخدام genkit.Handler.
يمكنك عرضها باستخدام خادم HTTP عادي كما تفعل عادةً باستخدام حزمة http من المكتبة العادية، ولكن يوفّر Genkit أيضًا مكوّنًا إضافيًا server يساعد في بعض النماذج الشائعة للخادم، مثل التعامل مع إشارات إيقاف التشغيل بسلاسة.
استبدِل محتوى main.go بالرمز أدناه لإنشاء خادم الويب.
package main
import (
"context"
"errors"
"fmt"
"log"
"net/http"
"os"
"github.com/firebase/genkit/go/ai"
"github.com/firebase/genkit/go/genkit"
"github.com/firebase/genkit/go/plugins/googlegenai"
"github.com/firebase/genkit/go/plugins/server"
)
func main() {
ctx := context.Background()
PORT := os.Getenv("PORT")
if PORT == "" {
PORT = "8080"
}
listenAddr := ":" + PORT
// Initialize Genkit with the Vertex AI plugin
g := genkit.Init(ctx,
genkit.WithPlugins(&googlegenai.VertexAI{}),
)
// Input schema for the glowUp flow
type Input struct {
URL string `json:"url,omitempty"`
ContentType string `json:"contentType,omitempty"`
}
genkit.DefineFlow(g, "glowUp", func(ctx context.Context, input Input) (string, error) {
prompt := genkit.LookupPrompt(g, "glowup")
if prompt == nil {
return "", errors.New("prompt 'glowup' not found")
}
resp, err := prompt.Execute(ctx, ai.WithInput(input))
if err != nil {
return "", fmt.Errorf("generation failed: %w", err)
}
return resp.Media(), nil
})
log.Printf("GlowUp Flow Server started. Listening on %s", listenAddr)
mux := http.NewServeMux()
for _, flow := range genkit.ListFlows(g) {
mux.HandleFunc("POST /"+flow.Name(), genkit.Handler(flow))
}
if err := server.Start(ctx, listenAddr, mux); err != nil {
// Check if the error is due to context cancellation
if ctx.Err() != nil {
log.Println("GlowUp server shutting down gracefully...")
return
}
log.Fatal(err)
}
}
يمكنك تشغيل هذه الخدمة على الجهاز أو في السحابة الإلكترونية. لتشغيل البرنامج محليًا، يمكنك تشغيل الملف مباشرةً لأنّ البرنامج أصبح مكتملاً الآن، لذا لا نحتاج إلى تشغيله من خلال واجهة سطر أوامر Genkit. على سبيل المثال:
go run main.go
بما أنّ هذه العملية تؤدي إلى حظر، عليك تشغيل نافذة Terminal ثانية لاختبارها. أسرع طريقة هي استخدام الأمر curl:
curl -sS -X POST http://localhost:8080/glowUp \
-H "Content-Type: application/json" \
-d '{"data":{"url": $IMAGE_URL, "contentType":"image/jpeg"}}' \
> result.json
بما أنّ هذه استجابة من الخادم، علينا فك ترميز صورة base64:
cat result.json | jq -r '.result' | awk -F ',' '{print $2}' | base64 -d > restored.png
نشر خدمة الويب على Cloud Run
لا بأس في أن يعمل هذا الخادم "على جهازي"، ولكن في العالم المثالي، سننشره في مكان آخر يمكن لجميع المستخدمين الوصول إليه. من أكثر الطرق ملاءمةً لنشر خدمات مثل هذه هي استخدام ميزة "النشر من المصدر" في Cloud Run. باستخدام هذه الميزة، لن تحتاج حتى إلى إنشاء الحاوية بنفسك، فكل شيء يتم بشكل مبرمَج.
لنشر هذه الخدمة في Cloud Run باستخدام النشر من المصدر، نفِّذ الأمر التالي (استبدِل رقم تعريف المشروع برقم تعريف مشروعك):
gcloud run deploy glowup --source . --region us-central1 --no-allow-unauthenticated --set-env-vars GOOGLE_GENAI_USE_VERTEXAI=True,GOOGLE_CLOUD_LOCATION=$GOOGLE_CLOUD_LOCATION,GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT
قد يستغرق اكتمال عملية النشر بضع دقائق. بعد الانتهاء، يمكنك اختبار نقطة النهاية من خلال إرسال طلب آخر عبر curl:
GLOWUP_URL=$(gcloud run services describe glowup --region us-central1 --format='value(status.url)')
curl -X POST "$GLOWUP_URL/glowUp" \
-H "Authorization: Bearer $(gcloud auth print-identity-token)" \
-H "Content-Type: application/json" \
-d "{\"data\":{\"url\":\"$IMAGE_URL\", \"contentType\":\"image/jpeg\"} }" \
> result.json
مرة أخرى، نحتاج إلى فك ترميز صورة base64:
cat result.json | jq -r '.result' | awk -F ',' '{print $2}' | base64 -d > restored_cloudrun.png
أصبح لدينا الآن خادم ويب يعمل بكامل طاقته لاستعادة الصور.
اختياري: "البرمجة الوصفية" لتطبيق عميل
كتابة الرموز البرمجية يدويًا ممتعة، ولكنّها قد تكون صعبة إذا لم يسبق لك تنفيذ نوع معيّن من المشاريع. لحسن الحظ، لدينا اليوم وكلاء ترميز يمكنهم مساعدتنا في تسريع العملية.
في هذه الخطوة، بدلاً من كتابة الرمز بأنفسنا، سنطلب من Gemini CLI (أو وكيل الترميز المفضّل لديك) تنفيذ العمل نيابةً عنا. استخدِم الطلب التالي:
GlowUp is a photo restoration service that takes a restoration request as input and returns a restored picture as output. Your task is to create a client application that uses this server to process image urls and save a restored file locally.
TODO:
- Write a CLI application that receives three arguments: an url (required), content type (optional, defaults to image/jpeg) and addr (server address, optional, defaults to localhost:8080)
- The CLI should send a POST request to the /glowUp endpoint in the server with the body '{"data":{"url": <url>, "contentType": <contentType>} }'
- The server response should be parsed by stripping the "data:" prefix. The remainder will have the format <mimeType>;base64,<encoded imageData>
- Extract the mime type and convert to a file extension using the mime package
- Extract the image data and decode it using the base64 package
Save a file named "restored" + the detected file extension
Acceptance Criteria:
- The client builds successfully
- Use the client to restore the image https://tile.loc.gov/storage-services/service/pnp/fsa/8c01000/8c01700/8c01765v.jpg
- Check that restored.png exists after processing the image above
قد يحتاج الوكيل إلى إعادة تنظيم الملفات قليلاً لأنّه لا يمكن أن تكون هناك دالتان "رئيسيتان" في الوحدة نفسها. راقِب عمله ووجِّهه نحو التنفيذ الصحيح من خلال تزويده برمز الخادم أو مقتطفات منه إذا لزم الأمر.
التنظيف بعد التمرين العملي
7. الخاتمة
تهانينا! لقد نجحت في إنشاء تطبيق لاستعادة الصور بدقة عالية باستخدام Genkit وNano Banana Pro،
في هذا الدرس التطبيقي حول الترميز، تعرّفت على كيفية:
- إعداد بيئة لتطوير تطبيقات Genkit Go
- إنشاء طلبات متعددة الوسائط باستخدام
dotprompt - إنشاء مسارات Genkit باستخدام نماذج الطلبات
- استخدام Nano Banana Pro لمعالجة الصور
- تجميع تدفقات Genkit كتطبيقات سطر أوامر وخدمات ويب
- نشر تطبيقات Genkit على Cloud Run
بعد الانتهاء من الاختبار، تذكَّر تنظيف البيئة.
الخطوات التالية
يمكنك مواصلة رحلة التعلّم من خلال استكشاف الدروس التطبيقية الأخرى حول الترميز في هذه المنصة، أو إجراء تحسينات على تطبيق glowUp بنفسك.
إذا كنت بحاجة إلى بعض الأفكار لإجراء تحسينات، يمكنك تجربة ما يلي:
- تفعيل واجهة سطر الأوامر glowUp لاستعادة الملفات المخزَّنة على الجهاز
- إنشاء واجهة أمامية لخدمة الويب GlowUp
- رصد نوع MIME تلقائيًا من البيانات
- تنفيذ أنواع أخرى من معالجة الصور (من صورة إلى رسم، ومن رسم إلى صورة، ومن رسم تخطيطي إلى عمل فني نهائي، وما إلى ذلك)
- إنشاء برنامج العميل أو تحسينه (ربما إنشاء تطبيق للهواتف الذكية؟)
الخيارات لا تحصى. إذا كانت فكرة العمل بمفردك تبدو مخيفة بعض الشيء، يمكنك دائمًا الاستعانة بوكيل ترميز مثل Gemini CLI أو Antigravity. وإذا أردت الاستفادة من Genkit بشكل أكبر، يمكنك استخدام وكلاء الترميز مع خادم Genkit MCP لتسهيل عملك بشكل كبير.
أخيرًا، إذا أردت الوصول إلى الرمز الكامل لهذا المستودع، يمكنك العثور عليه هنا.
مع أطيب التحيّات،