playfetch

PlayFetch

يجعل PlayFetch إضافة ميزات نموذج اللغة الكبيرة إلى تطبيقك أمرًا سريعًا وغير مؤلم.

خلفية

لقد غيرت LLMs طريقة عمل فرق المنتج. يتم الآن إنشاء أجزاء كبيرة ومتزايدة من التطبيقات باستخدام اللغة الطبيعية. غالبًا ما يكون هناك أعضاء فريق غير هندسيين مشاركين في هذه العملية - استراتيجيو المحتوى الذين يهتمون بأسلوب النص الذي تم إنشاؤه وتقديمه، وخبراء المجال الذين يقدمون معرفة متخصصة للغاية للمحتوى الذي تم إنشاؤه، والمصممين ومديري المنتجات الذين لديهم فهم عميق لـ احتياجات منتجاتهم. مع أعضاء الفريق الجدد المشاركين في النماذج الأولية وتطوير وصيانة الأجزاء المهمة من التطبيقات جنبًا إلى جنب مع الفريق الهندسي، هناك الكثير من التفاعلات الجديدة.

تحتاج هذه التفاعلات الجديدة بين المهندسين وبقية أعضاء الفريق إلى أدوات جديدة. لا يريد المهندسون توزيع نص عادي عبر قواعد التعليمات البرمجية الخاصة بهم مع طلبات مستمرة للتحديثات فقط ليجدوا أن الإصدار الجديد ليس أفضل في الواقع. لا يرغب المساهمون في المطالبات أو السلاسل في الانتظار حتى يقوم المهندس بدمج تحديثاتهم قبل أن يكتشفوا أنهم لا يعملون كما هو متوقع. يعمل PlayFetch على حل هذه المشكلات والعديد من نقاط الضعف الأخرى التي لاحظناها في الشركات التي تعمل بهذه الطريقة.

ما هو بلاي فيتش؟

• ساحة لعب سريعة وبديهية مبنية على التعاون من خلال التعليقات والتعليقات التوضيحية والتصنيفات والتقييمات.
• نظام إصدار غير مدمر يمكن لأي عضو في الفريق استخدامه بشفافية.
• بيئة اختبار تتضمن استيراد البيانات وتصديرها، وسلاسل القياس، واختبار روبوتات الدردشة الآلية.
• منصة LLM تتكامل بسلاسة مع أدوات التحكم في المصدر وإدارة المشاريع ومخازن المتجهات.
• حل استضافة غير محدد النموذج مع واجهة برمجة تطبيقات موحدة بسيطة تدعم المكالمات البسيطة والدردشة والمقاطعات اليدوية.
• حل تحليلي ومراقبة يركز على احتياجات ميزات LLM.

نشر PlayFetch على Google Cloud

تم تحسين PlayFetch للتشغيل على Google Cloud Platform. اتبع الإرشادات أدناه لإعداد المثيل الخاص بك وتشغيله. سنفترض أنك قمت بتقسيم مستودع PlayFetch الرسمي على https://github.com/yello-xyz/playfetch (حتى تتمكن من إعداد التكامل المستمر). إذا كنت تخطط لإجراء تغييرات على التعليمات البرمجية، فيمكنك تنفيذ هذه التعليمات عدة مرات لإعداد مثيلات منفصلة للتطوير والتجهيز والإنتاج.

تكوين مشروع جديد

• قم بإعداد حساب Google Cloud Platform الخاص بك على https://cloud.google.com/.
• قم بالوصول إلى Cloud Console على https://console.cloud.google.com.
• انتقل إلى IAM & Admin → إدارة الموارد وانقر على إنشاء مشروع .
• اختر اسمًا فريدًا (لا يمكن تغييره لاحقًا) وانقر فوق "إنشاء" .
• انتقل إلى الفوترة ، وضمن إدارة الحساب ، تأكد من تمكين الفوترة للمشروع الجديد.

تكوين واجهات برمجة التطبيقات

• انتقل إلى واجهات برمجة التطبيقات والخدمات → تمكين واجهات برمجة التطبيقات والخدمات .
• تأكد من تحديد المشروع الذي تم إنشاؤه حديثًا في محدد المشروع في الأعلى.
• انقر فوق تمكين واجهات برمجة التطبيقات والخدمات .
• ابحث عن App Engine Admin API وانقر على "تمكين" .
• ابحث عن Cloud Build API وانقر على "تمكين" .
• ابحث عن Cloud Datastore API وانقر على ENABLE .
• ابحث عن واجهة برمجة تطبيقات Cloud Scholer وانقر على "تمكين" .
• ابحث عن البيئة المرنة لمحرك تطبيقات Google وانقر على "تمكين" .
• ابحث عن واجهة برمجة تطبيقات إدارة الهوية والوصول (IAM) وانقر على تمكين .
• ابحث عن Vertex AI API وانقر فوق ENABLE .

تكوين تطبيق App Engine

• انتقل إلى App Engine ← لوحة المعلومات وانقر على إنشاء تطبيق .
• اختر موقعًا (لا يمكن تغييره لاحقًا).
• اترك خيار حساب الخدمة مفتوحًا (سنستخدم الخيار الافتراضي) وانقر فوق التالي .
• تجاهل لوحة النشر (انقر فوق سأفعل هذا لاحقًا ).

تكوين مخزن البيانات

• انتقل إلى مخزن البيانات .
• إذا كنت لا ترى مخزن البيانات (الافتراضي) ، فانتظر دقيقة وقم بالتحديث.
• حدد مخزن البيانات (الافتراضي) .
• حدد مدة البقاء (TTL) في الشريط الجانبي، ثم انقر فوق إنشاء سياسة .
• قم بتعيين النوع على _nextauth_token وخاصية Timestamp بحيث تنتهي صلاحيتها وانقر فوق "إنشاء" .
• قم بإنشاء سياسة أخرى باستخدام ذاكرة التخزين المؤقت اللطيفة وانتهاء صلاحية الخاصية عند .

تكوين دلو التخزين

• انتقل إلى التخزين السحابي → الجرافات وحدد الجرافة [اسم المشروع] .appspot.com .
• ضمن الأذونات ، انقر فوق منح الوصول .
• أضف جميع المستخدمين الرئيسيين وقم بتعيين دور عارض كائن التخزين .
• انقر فوق حفظ والسماح بالوصول العام (سيتم استخدام هذه المجموعة لتخزين الصور الرمزية).

إنشاء حساب خدمة البناء

• انتقل إلى IAM & Admin → حسابات الخدمة وانقر فوق إنشاء حساب خدمة .
• اختر اسمًا فريدًا وانقر فوق "إنشاء ومتابعة" .
• حدد دور مستخدم حساب الخدمة .
• انقر فوق إضافة دور آخر وحدد App Engine Deployer .
• انقر فوق إضافة دور آخر وحدد وكيل خدمة البيئة المرنة لـ App Engine .
• انقر فوق إضافة دور آخر وحدد مسؤول خدمة App Engine .
• انقر فوق إضافة دور آخر وحدد حساب خدمة Cloud Build .
• انقر على إضافة دور آخر وحدد مسؤول فهرس Cloud Datastore .
• انقر فوق "إضافة دور آخر" وحدد مسؤول برنامج جدولة السحابة .
• انقر فوق "متابعة" ثم "تم" .

[اختياري] قم بتكوين المجال المخصص

• انتقل إلى محرك التطبيقات → الإعدادات .
• ضمن المجالات المخصصة، انقر فوق إضافة مجال مخصص .
• أدخل النطاق المخصص والنطاقات الفرعية التي تريد استخدامها (باتباع الإرشادات للتحقق من الملكية).
• انقر فوق "متابعة" ثم "تم" .
• أضف السجلات المعروضة إلى تكوين DNS لموفر المجال المخصص الخاص بك.

[اختياري لكن موصى به] قم بتكوين مصادقة مستخدم Google OAuth

• انتقل إلى واجهات برمجة التطبيقات والخدمات → شاشة موافقة OAuth .
• اختر نوع المستخدم الداخلي أو الخارجي حسب حالة الاستخدام الخاصة بك وانقر فوق "إنشاء" .
• املأ الحقول المطلوبة، وانقر على "حفظ ومتابعة" ، ثم انقر على "إضافة أو إزالة النطاقات" .
• تحقق من النطاق .../auth/userinfo.profile و .../auth/userinfo.email ، ثم انقر فوق UPDATE و SAVE AND CONTINUE .
• إذا اخترت نوع المستخدم الخارجي أعلاه، فيمكنك إضافة بعض حسابات الاختبار (قبل نشر التطبيق إلى الإنتاج). تأكد من تضمين عنوان البريد الإلكتروني الذي تريد استخدامه للمستخدم الإداري الأول. لاحظ أنك ستظل بحاجة إلى منح هؤلاء المستخدمين إمكانية الوصول إلى PlayFetch أيضًا.
• انقر فوق حفظ ومتابعة ثم العودة إلى لوحة التحكم .
• حدد بيانات الاعتماد في الشريط الجانبي، ثم انقر على إنشاء بيانات الاعتماد ومعرف عميل OAuth .
• حدد تطبيق الويب كنوع التطبيق واختر اسمًا.
• ضمن أصول JavaScript المعتمدة ، أضف https:// [project-name] .appspot.com (والنطاق المخصص إذا كان لديك واحدًا). إذا كنت تريد أيضًا استخدام مصادقة Google عند تشغيل التطبيق محليًا، فأضف http://localhost:3000 أيضًا.
• ضمن عناوين URL لإعادة التوجيه المعتمدة ، أضف https:// [project-name] .appspot.com/api/auth/callback/google (وعنوان URL مشابه لأي نطاق مخصص). إذا كنت تريد أيضًا استخدام مصادقة Google عند تشغيل التطبيق محليًا، فأضف http://localhost:3000/api/auth/callback/google أيضًا.
• انقر فوق "إنشاء" وانسخ معرف العميل وسر العميل الذي تم إنشاؤه لاستخدامهما في إعداد مشغل الإنشاء أدناه.

تكوين البناء

• انتقل إلى Cloud Build → المشغلات وانقر فوق CONNECT REPOSITORY .
• حدد مصدر GitHub (تطبيق Cloud Build GitHub) وانقر فوق "متابعة" لمصادقة حساب GitHub حيث قمت بتقسيم المستودع (في نافذة منبثقة).
• حدد المستودع المتشعب، وحدد المربع الموجود أسفله، وانقر فوق CONNECT .
• انقر فوق إنشاء مشغل .
• اختر اسمًا للبناء الخاص بك.
• ضمن التكوين ، حدد ملف تكوين Cloud Build (yaml أو json) .
• للحصول على الحد الأدنى من الإعداد، ستحتاج إلى إضافة متغيرات الاستبدال التالية إلى مشغل البناء الخاص بك (في القسم خيارات متقدمة ) عن طريق النقر فوق ADD VARIABLE :
  • _ENCRYPTION_KEY : سلسلة عشوائية مكونة من 64 رقمًا سداسيًا عشريًا .
  • _NEXTAUTH_SECRET : سلسلة عشوائية مكونة من 32 حرفًا على الأقل.
  • _NEXTAUTH_URL : عنوان URL العام لمثيلك، إما مجالًا مخصصًا إذا كان لديك واحدًا أو https:// [project-name] .appspot.com .
  • _GCLOUD_STORAGE_BUCKET : اسم مجموعة التخزين السحابي حيث سمحت بالوصول العام، على سبيل المثال [project-name] .appspot.com .
  • _NOREPLY_EMAIL_USER و_ NOREPLY_EMAIL_PASSWORD : حساب Gmail الذي سيتم استخدامه لرسائل البريد الإلكتروني الصادرة الخاصة بالمعاملات. يمكن أن يكون حسابًا مخصصًا في Google Workspace (بكلمة مرور عادية)، أو حساب Gmail منفصلًا (بكلمة مرور التطبيق). راجع التعليمات أدناه إذا كنت بحاجة إلى استخدام مزود بريد إلكتروني آخر.
• إذا قمت بتكوين مصادقة Google أعلاه، فيجب عليك أيضًا إضافة المتغيرات التالية:
  • _GOOGLE_CLIENT_ID و_ GOOGLE_CLIENT_SECRET : القيم التي نسختها أعلاه بعد إنشاء بيانات اعتماد OAuth.
• ضمن حساب الخدمة ، حدد حساب الخدمة الذي قمت بإنشائه أعلاه.
• انقر فوق إنشاء .
• انقر فوق RUN بجوار المشغل الذي تم إنشاؤه حديثًا، ثم انقر فوق RUN TRIGGER.
• حدد "السجل" في الشريط الجانبي، وانتظر حتى تتأكد من اكتمال البناء بنجاح (قد يستغرق ذلك من 10 إلى 15 دقيقة).

قم بتهيئة بيئة PlayFetch الخاصة بك

• اختر عنوان بريد إلكتروني سيتم استخدامه لتسجيل الدخول للمستخدم الإداري الأولي.
• افتح متصفحًا وانتقل إلى https:// [project-name] .appspot.com/api/admin/init?admin= [[email protected]] (تأكد من تحديد عنوان البريد الإلكتروني الصحيح في الاستعلام).
• ستقوم نقطة النهاية هذه بتشغيل برنامج نصي لتهيئة مخزن البيانات (والذي قد يستغرق دقيقة واحدة) ولكن لن تتمكن من تشغيله إلا مرة واحدة (ما لم تقم بإعادة إنشاء مخزن البيانات).
• بمجرد اكتمال البرنامج النصي، انسخ قيم _PLAYFETCH_API_KEY و_ PLAYFETCH_ENDPOINT_URL التي تظهر في الرد.
• انتقل إلى Cloud Build → Triggers ، وانقر فوق المشغل الذي قمت بإنشائه، وأضف متغيري الاستبدال الإضافيين من الخطوة أعلاه، وانقر فوق SAVE .
• قم بتشغيل مشغل البناء الخاص بك مرة أخرى باستخدام المتغيرات المضافة. قد يحتاج هذا الإصدار إلى إنشاء فهارس مخزن بيانات مفقودة، لذا من الأفضل الانتظار حتى يكتمل مرة أخرى.

يجب أن تكون الآن قادرًا على الانتقال إلى https:// [project-name] .appspot.com وتسجيل الدخول باستخدام عنوان البريد الإلكتروني الذي حددته للمستخدم الإداري الأول. يمكنك استخدام إما مصادقة Google (إذا تم تكوينها) أو روابط البريد الإلكتروني (بشرط أن يتم إعداد متغيرات _NOREPLY_EMAIL بشكل صحيح). ويمكن منح مستخدمين إضافيين حق الوصول في لوحة الإدارة.

تشغيل PlayFetch محليًا

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

تثبيت العقدة وnpm

أسهل طريقة لتثبيت أحدث إصدار من العقدة و npm هي تشغيل أحدث برنامج تثبيت.

استنساخ المستودع

قم إما بالفتح باستخدام GitHub Desktop والاستنساخ إلى دليل محلي أو الاتصال بـ GitHub باستخدام SSH وتشغيل git clone [email protected]:yello-xyz/playfetch.git . إذا كنت قد قمت بالفعل بتشعب المستودع، فيمكنك استنساخه بدلاً من ذلك.

تكوين البيئة

لتشغيل التطبيق محليًا، ستحتاج إلى إضافة بعض المتغيرات نفسها إلى ملف .env.local المحلي (يتم تجاهل هذا الملف بواسطة التحكم بالمصادر لتجنب تسرب المفاتيح). يمكن أن تكون هذه هي نفس القيم التي حددتها في مشغل إنشاء Google Cloud الخاص بك لمثيل التطوير الخاص بك (بافتراض أنك تقوم بتشغيل مثيل منفصل للإنتاج لأنك لا تريد المخاطرة بتسريب هذه المفاتيح)، باستثناء _NEXTAUTH_URL حيث يجب تحديد القيمة http://localhost:3000.

يمكنك الوصول إلى مخزن البيانات في Google Cloud من جهازك المحلي (مرة أخرى بافتراض أنك تقوم بتشغيل نسخة تطوير منفصلة حتى لا تفسد أو تتسرب بيانات الإنتاج عن طريق الخطأ) عن طريق تثبيت Google Cloud CLI وتهيئته كما هو موضح هنا (يمكنك تخطي الخطوات الأخرى). قم بتشغيل الأوامر التالية لتسجيل الدخول باستخدام حساب Google الخاص بك:

• gcloud auth login
• gcloud init
• gcloud auth application-default login
• gcloud init

بناء وتشغيل

يجب أن تكون الآن قادرًا على تشغيل الأوامر التالية:

• npm install
• npm run build
• npm run start

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

npm run dev

لتشغيل جميع الاختبارات مرة واحدة:

npm run test

لمراقبة التغييرات وإعادة تشغيل مجموعات الاختبار ذات الصلة تلقائيًا:

npm run watch

ميزات اختيارية

من أجل توسيع الحد الأدنى من الإعداد، يمكنك تكوين متغيرات البيئة التالية (إما في مشغل إنشاء GCP الخاص بك أو في ملف .env.local المحلي) لتمكين بعض الميزات الإضافية.

التكامل

• _GITHUB_CLIENT_ID ، _GITHUB_CLIENT_SECRET : يمكن استخدامه لتكوين مصادقة GitHub OAuth (على غرار Google). يتطلب إعداد تطبيق GitHub OAuth.
• _GITHUB_APP_CLIENT_ID , _GITHUB_APP_CLIENT_SECRET , _GITHUB_APP_ID , _GITHUB_APP_PRIVATE_KEY , _NEXT_PUBLIC_GITHUB_APP_INSTALL_LINK : يمكن استخدامها لتكوين تكامل التحكم بالمصدر. يتطلب إعداد تطبيق GitHub.
• _LINEAR_APP_CLIENT_ID ، _LINEAR_APP_CLIENT_SECRET ، _LINEAR_APP_WEBHOOK_SECRET : يمكن استخدامه لتكوين تكامل إدارة المهام. يتطلب إعداد تطبيق Linear أيضًا.
• _NOTION_TOKEN، _NOTION_ONBOARDING_PAGE_ID، _NOTION_WAITLIST_PAGE_ID : يمكن استخدامه لمزامنة الاشتراكات في قائمة الانتظار تلقائيًا وردود الاستطلاع على Notion. يتطلب إعداد تطبيق Notion.

التحليلات

• _GOOGLE_ANALYTICS_API_SECRET ، _GOOGLE_ANALYTICS_MEASUREMENT_ID : يمكن استخدامه لتهيئة التحليلات من جانب الخادم (GA4).
• _NEXT_PUBLIC_GOOGLE_TAG_MANAGER_ID , _NEXT_PUBLIC_COOKIE_DOMAIN , _NEXT_PUBLIC_COOKIE_NAME : يمكن استخدامه لتكوين ملفات تعريف الارتباط والتحليلات من جانب العميل (Google Tag Manager).

بيئة

• _GOOGLE_ANALYTICS_DASHBOARD_URL , _GOOGLE_ANALYTICS_REPORTS_URL , _GOOGLE_SEARCH_CONSOLE_URL , _INTEGRATION_TEST_URL , _SERVER_LOGS_URL : يمكن استخدامها لإضافة روابط تشخيصية متنوعة في لوحة المشرف.
• _NEXT_PUBLIC_DOCS_URL ، _NEXT_PUBLIC_SUPPORT_EMAIL : يمكن استخدامه لإنشاء الروابط إلى التوثيق والدعم في مساحة العمل والأشرطة الجانبية للمشروع.
• _NOREPLY_EMAIL_HOST ، _NOREPLY_EMAIL_PORT : يمكن استخدامه لتكوين موفر بريد إلكتروني بديل لرسائل البريد الإلكتروني الخاصة بالمعاملات الصادرة.
• _API_URL : يمكن استخدامه لتقسيم حركة المرور بين موقع الويب وواجهة برمجة التطبيقات، على سبيل المثال، إذا كان لديك نطاقات فرعية منفصلة تشير إلى المثيل الخاص بك.

رخصة

PlayFetch مفتوح المصدر بموجب ترخيص MIT متساهل.

يرجى ملاحظة أن PlayFetch يستخدم CodeMirror باعتباره تابعًا. إذا كنت تستخدم CodeMirror تجاريًا، فهناك توقع اجتماعي (ولكن ليس قانونيًا) بأنك تساعد في تمويل صيانته.

المساهمة

يتم تطوير PlayFetch على GitHub. المساهمات هي موضع ترحيب. لا تتردد في فتح المشكلات أو فتح طلبات السحب عند إصلاح الأخطاء أو إضافة الميزات. للبدء، يمكن العثور على بعض الإلهام في TODO.md.