من الفكرة إلى التنفيذ: إنشاء دالة ذكاء اصطناعي مخصّصة لوصف الصور

مع وكيل الذكاء الاصطناعي (AI agent) الخاص بنا، يمكنكم تجاوز إجراءات المحرر القياسية وإضافة وظائف مخصصة مصممة لاحتياجاتكم. يستعرض هذا المنشور إنشاء دالة describeImage ويشرح كيف تحول الصور إلى عناوين وتسميات توضيحية ونصوص بديلة يمكن الوصول إليها.

الفكرة

الهدف بسيط. حددوا صورة، وقدموا تعليمات قصيرة، واحصلوا على نص مُولّد يوضع بالضبط حيث تحتاجونه. تدعم الوظيفة حالات الاستخدام الشائعة مثل عناوين الصور، والتسميات التوضيحية، والنص البديل، مع تجنب الافتراضات حول نية المستخدم من خلال الاعتماد على مطالبات (prompts) صريحة.

تصميم الوظيفة

لإتاحة الوظيفة لمحرك ONLYOFFICE AI، تم تعريفها كـ RegisteredFunction. يحدد هذا التعريف اسم الوظيفة، والمعلمات المتوقعة، وأمثلة للمطالبات التي توضح الاستخدام المقصود.

  let func = new RegisteredFunction({
    name: "describeImage",
    description:
      "Allows users to select an image and generate a meaningful title, description, caption, or alt text for it using AI.",
    parameters: {
      type: "object",
      properties: {
        prompt: {
          type: "string",
          description:
            "instruction for the AI (e.g., 'Add a short title for this chart.')",
        },
      },
      required: ["prompt"],
    },
    examples: [
      {
        prompt: "Add a short title for this chart.",
        arguments: { prompt: "Add a short title for this chart." },
      },
      {
        prompt: "Write me a 1-2 sentence description of this photo.",
        arguments: {
          prompt: "Write me a 1-2 sentence description of this photo.",
        },
      },
      {
        prompt: "Generate a descriptive caption for this organizational chart.",
        arguments: {
          prompt:
            "Generate a descriptive caption for this organizational chart.",
        },
      },
      {
        prompt: "Provide accessibility-friendly alt text for this infographic.",
        arguments: {
          prompt:
            "Provide accessibility-friendly alt text for this infographic.",
        },
      },
    ],
  });

يخدم هذا التعريف غرضين:

1. يُعْلِم محرك ONLYOFFICE AI بقدرات الوظيفة والمدخلات المتوقعة.
2. يوفر أمثلة للاستخدام لتوجيه كل من الذكاء الاصطناعي والمستخدمين النهائيين.

تنفيذ المنطق البرمجي

تحتوي طريقة call على الوظيفة الفعلية التي يتم تنفيذها عندما يستدعي المستخدم الوظيفة:

1. استرجاع الصورة المحددة – باستخدام GetImageDataFromSelection، نجلب الصورة من المستند. نقوم أيضًا بتصفية الصور النائبة لضمان نتائج ذات مغزى من الذكاء الاصطناعي.
2. بناء مطالبة الذكاء الاصطناعي – يتم دمج تعليمات المستخدم مع سياق الصورة المحددة لإنشاء مطالبة واضحة وقابلة للتنفيذ.
3. التحقق من توافق نموذج الذكاء الاصطناعي – النماذج القادرة على الرؤية فقط (مثل GPT-4V أو Gemini) يمكنها معالجة الصور. نقوم بتنبيه المستخدم إذا كان نموذجه الحالي لا يمكنه التعامل مع الصور.
4. إرسال الطلب إلى الذكاء الاصطناعي – يتم إرسال الصورة والمطالبة إلى محرك الذكاء الاصطناعي عبر chatRequest، مع جمع النص المولد في الوقت الفعلي.
5. إدراج النص المولد بواسطة الذكاء الاصطناعي في المستند – تكتشف الوظيفة ما إذا كانت هناك صورة محددة أم لا، وتقوم بإدراج النتيجة بشكل مناسب.
6. معالجة الأخطاء – تتعامل الوظيفة بمرونة مع الصور المفقودة، أو النماذج غير المدعومة، أو أخطاء الذكاء الاصطناعي غير المتوقعة، وتوفر رسائل واضحة للمستخدم.

1. جلب الصورة المحددة

في ONLYOFFICE، يشار إلى الصور الموجودة في المستند باسم drawings (رسومات). لمعالجة صورة حددها المستخدم، نستخدم واجهة برمجة تطبيقات (API) إضافة ONLYOFFICE:

    let imageData = await new Promise((resolve) => {
        window.Asc.plugin.executeMethod(
          "GetImageDataFromSelection",
          [],
          function (result) {
            resolve(result);
          }
        );
      });

• GetImageDataFromSelection هي طريقة في إضافة ONLYOFFICE تستخرج الصورة المحددة حاليًا كـ سلسلة مشفرة بنظام base64.
• النتيجة عبارة عن كائن (object)، عادةً:

{
  "src": "data:image/png;base64,iVBORw0K...",
  "width": 600,
  "height": 400
}

تحتوي سلسلة src هذه على الصورة بالكامل بـ تنسيق Base64، والتي يمكن إرسالها مباشرة إلى نماذج الذكاء الاصطناعي التي تقبل بيانات الصور.

اعتبارات رئيسية:

• إذا لم يتم تحديد صورة، تكون imageData بقمية null.
• قد يحدد بعض المستخدمين رسومات نائبة أو مستطيلات فارغة. على سبيل المثال، يستخدم ONLYOFFICE مستطيلاً أبيض صغيرًا كعنصر نائب للصور الفارغة. نقوم بالمقارنة مع تمثيله بنظام base64 لتصفيتهم:

   const whiteRectangleBase64 =   "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
      if (imageData.src === whiteRectangleBase64) {
        console.log("describeImage: Image is white placeholder");
        await insertMessage("Please select a valid image first.");
        return;
      }

2. تحضير الصورة للذكاء الاصطناعي

تتوقع نماذج الذكاء الاصطناعي الصور كـ عناوين URL أو بيانات مشفرة بنظام base64، عادةً في حقل مثل image_url. في وظيفتنا، نمرر الصورة مع مطالبة نصية في مصفوفة مهيكلة:

   let messages = [
        {
          role: "user",
          content: [
            { type: "text", text: argPrompt },
            {
              type: "image_url",
              image_url: { url: imageData.src, detail: "high" },
            },
          ],
        },
      ];

• type: “text” يوفر تعليمات المطالبة (على سبيل المثال، “أضف تعليقًا وصفيًا”).
• type: “image_url” يتضمن الصورة نفسها. يمكن لمحرك الذكاء الاصطناعي بعد ذلك تحليل الصورة وإنشاء نص ذي صلة.
• detail: “high” هو تلميح اختياري للنماذج لمعالجة الصورة بدقة كاملة.

منطق التحويل:

1. يوفر ONLYOFFICE الـ src كـ سلسلة base64.
2. يمكن لنماذج الذكاء الاصطناعي قبول إما بيانات base64 أو عنوان URL يمكن الوصول إليه. هنا، نستخدم base64 مباشرة لتجنب الرفع إلى خادم خارجي.
3. نقوم بتغليف الصورة في كائن متوافق مع واجهة برمجة تطبيقات (API) طلب الدردشة الخاصة بالذكاء الاصطناعي. يسمح هذا الهيكل بأنواع محتوى متعددة في رسالة واحدة.

3. إرسال الطلب إلى الذكاء الاصطناعي

بمجرد أن تكون لدينا الصورة والمطالبة مهيكلة، نستخدم محرك إضافة ONLYOFFICE AI:

     let requestEngine = AI.Request.create(AI.ActionType.Chat);
      await requestEngine.chatRequest(messages, false, async function (data) {
        console.log("describeImage: chatRequest callback data chunk", data);
        if (data) {
          resultText += data;
        }
      });

• يسمح AI.ActionType.Chat بإرسال رسائل بنمط الدردشة، حيث يتم تحليل المطالبة والصورة معًا.
• يجمع رد النداء (callback) أجزاء من نص استجابة الذكاء الاصطناعي في الوقت الفعلي.
• قبل الإرسال، نتحقق مما إذا كان نموذج الذكاء الاصطناعي المختار يدعم الرؤية. نماذج معينة فقط (GPT-4V، Gemini) يمكنها التعامل مع الصور:

 const allowVision = /(vision|gemini|gpt-4o|gpt-4v|gpt-4-vision)/i;
      if (!allowVision.test(requestEngine.modelUI.name)) {
        console.warn("describeImage: Model does not support vision", requestEngine.modelUI.name);
        await insertMessage(
          "⚠ This model may not support images. Please choose a vision-capable model (e.g. GPT-4V, Gemini, etc.)."
        );
        return;
      }

4. إدراج مخرجات الذكاء الاصطناعي في المستند

بعد تلقي مخرجات الذكاء الاصطناعي، يجب إدراج النص مرة أخرى في مستند ONLYOFFICE. يعالج المنطق حالتين:

1. صورة محددة: إدراج فقرة بعد الصورة.
2. لا توجد صورة محددة: إدراج فقرة بعد موقع المؤشر الحالي.

async function insertMessage(message) {
      console.log("describeImage: insertMessage called", message);
      Asc.scope._message = String(message || "");
      await Asc.Editor.callCommand(function () {
        const msg = Asc.scope._message || "";
        const doc = Api.GetDocument();
        const selected =
          (doc.GetSelectedDrawings && doc.GetSelectedDrawings()) || [];
        if (selected.length > 0) {
          for (let i = 0; i < selected.length; i++) {
            const drawing = selected[i];
            const para = Api.CreateParagraph();
            para.AddText(msg);
            drawing.InsertParagraph(para, "after", true);
          }
        } else {
          const para = Api.CreateParagraph();
          para.AddText(msg);
          let range = doc.GetCurrentParagraph();
          range.InsertParagraph(para, "after", true);
        }
        Asc.scope._message = "";
      }, true);

• يسترجع Api.GetSelectedDrawings() الصور المحددة حاليًا (الرسومات).
• ينشئ Api.CreateParagraph() كائن فقرة جديد.
• يدرج InsertParagraph(para, “after”, true) النص المولد مباشرة بعد الصورة أو الفقرة المحددة.
• يضمن هذا تكاملاً سلسًا: تظهر مخرجات الذكاء الاصطناعي دائمًا في السياق الصحيح.

5. التعامل مع الحالات الاستثنائية والأخطاء

تطلبت بعض التحديات اهتمامًا إضافيًا:

• لا توجد صورة محددة – حث المستخدم على تحديد واحدة.
• نموذج ذكاء اصطناعي غير مدعوم – تحذير المستخدم قبل إرسال الطلب.
• استجابة فارغة من الذكاء الاصطناعي – إعلام المستخدم بأن الذكاء الاصطناعي لم يتمكن من إنشاء وصف.
• أخطاء غير متوقعة – استخدام try/catch المتداخل لإنهاء أي إجراءات جارية للمحرر بأمان:

    } catch (e) {
      try {
        await Asc.Editor.callMethod("EndAction", ["GroupActions"]);
        await Asc.Editor.callMethod("EndAction", [
          "Block",
          "AI (describeImage)",
        ]);
      } catch (ee) {
       
      }

يضمن هذا بقاء المستند مستقرًا حتى إذا فشل الذكاء الاصطناعي أو الإضافة في منتصف العملية.

النتيجة النهائية

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

جربوا إنشاء وظائفكم المخصصة لتخصيص وظائف وكيل الذكاء الاصطناعي الخاص بنا. إذا قمتم ببناء شيء مفيد، فلا تترددوا في مشاركته معنا عبر صفحة الاتصال.