Od ideje do implementacije: Kreiranje prilagođene AI funkcije za opis slike

Uz naš AI agent, možete ići dalje od standardnih akcija editora i dodavati prilagođene funkcije prema sopstvenim potrebama. Ovaj članak prolazi kroz kreiranje funkcije describeImage i objašnjava kako ona pretvara slike u naslove, opise, natpise i pristupačni alt tekst.

Ideja

Cilj je jednostavan. Izaberite sliku, unesite kratku instrukciju i dobijte generisani tekst postavljen tačno tamo gde vam je potreban. Funkcija podržava uobičajene slučajeve upotrebe kao što su naslovi slika, opisi i alt tekst, dok izbegava pretpostavke o nameri korisnika oslanjajući se isključivo na eksplicitne upite.

Dizajniranje funkcije

Da bi funkcija bila dostupna ONLYOFFICE AI mehanizmu, definisana je kao RegisteredFunction. Ova definicija navodi naziv funkcije, očekivane parametre i primere upita koji prikazuju predviđenu upotrebu.

  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.",
        },
      },
    ],
  });

Ova definicija ima dve svrhe:

1. Obaveštava ONLYOFFICE AI mehanizam o mogućnostima funkcije i očekivanom ulazu.
2. Pruža primere upotrebe kako bi se usmerili i AI i krajnji korisnici.

Implementacija logike

Metoda call sadrži stvarnu funkcionalnost koja se izvršava kada korisnik pozove funkciju:

1. Preuzimanje izabrane slike – korišćenjem metode GetImageDataFromSelection preuzimamo sliku iz dokumenta. Takođe filtriramo placeholder slike kako bismo obezbedili smislen AI rezultat.
2. Kreiranje AI upita – korisnička instrukcija se kombinuje sa kontekstom izabrane slike kako bi se formirao jasan i upotrebljiv upit.
3. Provera kompatibilnosti AI modela – samo modeli sa podrškom za vizuelni sadržaj (kao što su GPT-4V ili Gemini) mogu obrađivati slike. Ako trenutni model to ne podržava, korisnik se obaveštava.
4. Slanje zahteva AI-ju – slika i upit se šalju AI mehanizmu putem chatRequest metode, a generisani tekst se prikuplja u realnom vremenu.
5. Umetanje AI-generisanog teksta u dokument – funkcija proverava da li je slika izabrana i u skladu s tim umeće rezultat.
6. Obrada grešaka – funkcija elegantno obrađuje situacije poput nepostojanja slike, nepodržanog modela ili neočekivanih AI grešaka, uz jasne poruke korisniku.

1. Preuzimanje izabrane slike

U ONLYOFFICE-u, slike u dokumentu se nazivaju drawings. Da bismo obradili sliku koju je korisnik izabrao, koristimo ONLYOFFICE plugin API:

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

• GetImageDataFromSelection je ONLYOFFICE plugin metoda koja izdvaja trenutno izabranu sliku kao Base64 enkodirani string.
• Rezultat je objekat, obično:

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

String src sadrži celu sliku u Base64 formatu, koji se može direktno poslati AI modelima koji prihvataju podatke o slici.

Ključne napomene:

• Ako nijedna slika nije izabrana, imageData je null
• Neki korisnici mogu izabrati placeholder grafiku ili prazne oblike. Na primer, ONLYOFFICE koristi mali beli pravougaonik kao placeholder za prazne slike. Njegovu Base64 vrednost koristimo za filtriranje:

   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. Priprema slike za AI

AI modeli očekuju slike kao URL-ove ili Base64 enkodirane podatke, obično u polju image_url. U našoj funkciji prosleđujemo sliku zajedno sa tekstualnim upitom u strukturisanom nizu:

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

• unesite: “tekst“ pruža uputstva (npr. „Dodaj opisni natpis“).
• unesite: “image_url“ uključuje samu sliku. AI mehanizam zatim može analizirati sliku i generisati relevantan tekst.
• detalj: “high“ je opcioni savet za modele da obrade sliku u punoj rezoluciji.

Logika transformacije:

1. ONLYOFFICE isporučuje src kao Base64 string.
2. AI modeli mogu prihvatiti Base64 podatke ili URL-ove. Ovde koristimo Base64 direktno kako bismo izbegli upload na eksterni server.
3. Slika se pakuje u strukturu kompatibilnu sa AI chat API-jem, što omogućava više tipova sadržaja u jednoj poruci.

3. Slanje zahteva AI-ju

Kada su slika i upit pripremljeni, koristimo ONLYOFFICE AI plugin mehanizam:

     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 omogućava slanje poruka u chat stil formatu, gde se tekst i slika analiziraju zajedno.
• Callback funkcija prikuplja delove AI odgovora u realnom vremenu.
• Pre slanja zahteva proveravamo da li izabrani AI model podržava obradu slika. Samo određeni modeli (GPT-4V, Gemini) imaju tu mogućnost:

 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. Umetanje AI rezultata u dokument

Nakon dobijanja AI rezultata, tekst se umeće nazad u ONLYOFFICE dokument. Logika pokriva dva slučaja:

1. Slika je izabrana: novi pasus se umeće odmah posle slike.
2. Slika nije izabrana: pasus se umeće posle trenutne pozicije kursora.

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() preuzima trenutno izabrane slike (drawings).
• Api.CreateParagraph() kreira novi objekat pasus.
• InsertParagraph(para, “after”, true) umeće generisani tekst odmah nakon izabrane slike ili pasusa.
• Ovo obezbeđuje besprekornu integraciju: AI rezultat se uvek pojavljuje u odgovarajućem kontekstu.

5. Obrada ivčnih slučajeva i grešaka

Neki izazovi zahtevali su dodatnu pažnju:

• Nema izabrane slike – korisnik se obaveštava da prvo izabere sliku.
• Nepodržan AI model – korisnik se upozorava pre slanja zahteva.
• Prazan AI odgovor – korisnik se obaveštava da opis nije mogao biti generisan.
• Neočekivane greške – koriste se ugnježdeni try/catch blokovi kako bi se bezbedno završile sve započete akcije editora:

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

Ovo osigurava da dokument ostane stabilan čak i ako AI ili plugin zakažu tokom izvršavanja.

Krajnji rezultat

Funkcija describeImage pokazuje kako prilagođene funkcije mogu proširiti AI agenta na male, ali veoma efikasne načine. Kombinovanjem jasnih upita sa logikom koja je svesna konteksta editora, možete izgraditi funkcionalnosti koje se prirodno uklapaju u realne radne tokove, umesto generičkih AI akcija.

Pokušajte da kreirate sopstvene prilagođene funkcije kako biste prilagodili mogućnosti našeg AI agenta. Ako napravite nešto korisno, slobodno podelite sa nama putem kontakt stranice.