Από την ιδέα στην υλοποίηση: Δημιουργία μιας προσαρμοσμένης λειτουργίας AI για περιγραφή εικόνων
Με τον πράκτορα AI μας, μπορείτε να υπερβείτε τις τυπικές ενέργειες του επεξεργαστή και να προσθέσετε προσαρμοσμένες λειτουργίες που ταιριάζουν στις ανάγκες σας. Αυτή η ανάρτηση περιγράφει τη δημιουργία της λειτουργίας describeImage και εξηγεί πώς μετατρέπει εικόνες σε τίτλους, λεζάντες και προσιτό κείμενο εναλλακτικής περιγραφής.
Η ιδέα
Ο στόχος είναι απλός. Επιλέξτε μια εικόνα, δώστε μια σύντομη οδηγία και λάβετε παραγόμενο κείμενο τοποθετημένο ακριβώς εκεί που το χρειάζεστε. Η λειτουργία υποστηρίζει κοινές περιπτώσεις χρήσης όπως τίτλοι εικόνων, λεζάντες και κείμενο alt, ενώ αποφεύγει υποθέσεις σχετικά με την πρόθεση του χρήστη βασιζόμενη σε ρητές οδηγίες.
Σχεδιασμός της λειτουργίας
Για να γίνει η λειτουργία διαθέσιμη στη μηχανή AI του ONLYOFFICE, ορίστηκε ως RegisteredFunction. Αυτός ο ορισμός καθορίζει το όνομα της λειτουργίας, τις αναμενόμενες παραμέτρους και παραδείγματα οδηγιών που αποδεικνύουν την προβλεπόμενη χρήση.
let func = new RegisteredFunction({
name: "describeImage",
description:
"Επιτρέπει στους χρήστες να επιλέξουν μια εικόνα και να δημιουργήσουν έναν ουσιαστικό τίτλο, περιγραφή, λεζάντα ή κείμενο alt για αυτήν χρησιμοποιώντας AI.",
parameters: {
type: "object",
properties: {
prompt: {
type: "string",
description:
"οδηγία για το AI (π.χ., 'Πρόσθεσε έναν σύντομο τίτλο για αυτό το διάγραμμα.')",
},
},
required: ["prompt"],
},
examples: [
{
prompt: "Πρόσθεσε έναν σύντομο τίτλο για αυτό το διάγραμμα.",
arguments: { prompt: "Πρόσθεσε έναν σύντομο τίτλο για αυτό το διάγραμμα." },
},
{
prompt: "Γράψε μου μια περιγραφή 1-2 προτάσεων για αυτή τη φωτογραφία.",
arguments: {
prompt: "Γράψε μου μια περιγραφή 1-2 προτάσεων για αυτή τη φωτογραφία.",
},
},
{
prompt: "Δημιούργησε μια περιγραφική λεζάντα για αυτό το οργανόγραμμα.",
arguments: {
prompt:
"Δημιούργησε μια περιγραφική λεζάντα για αυτό το οργανόγραμμα.",
},
},
{
prompt: "Πρόσφερε κείμενο alt φιλικό στην προσιτότητα για αυτό το infographic.",
arguments: {
prompt:
"Πρόσφερε κείμενο alt φιλικό στην προσιτότητα για αυτό το infographic.",
},
},
],
});
Αυτός ο ορισμός εξυπηρετεί δύο σκοπούς:
- Ενημερώνει τη μηχανή AI του ONLYOFFICE σχετικά με τις δυνατότητες και την αναμενόμενη εισαγωγή της λειτουργίας.
- Παρέχει παραδείγματα χρήσης για να καθοδηγήσει τόσο το AI όσο και τους τελικούς χρήστες.
Υλοποίηση της λογικής
Η μέθοδος call περιέχει τη πραγματική λειτουργικότητα που εκτελείται όταν ο χρήστης καλεί τη λειτουργία:
- Ανάκτηση της επιλεγμένης εικόνας – χρησιμοποιώντας το GetImageDataFromSelection, ανακτούμε την εικόνα από το έγγραφο. Φιλτράρουμε επίσης τις εικόνες placeholder για να εξασφαλίσουμε ουσιαστικά αποτελέσματα AI.
- Κατασκευή της οδηγίας AI – η οδηγία του χρήστη συνδυάζεται με το πλαίσιο της επιλεγμένης εικόνας για τη δημιουργία μιας σαφούς και εκτελέσιμης οδηγίας.
- Επαλήθευση συμβατότητας μοντέλου AI – μόνο μοντέλα με δυνατότητα όρασης (όπως GPT-4V ή Gemini) μπορούν να επεξεργαστούν εικόνες. Ειδοποιούμε τον χρήστη εάν το τρέχον μοντέλο του δεν μπορεί να χειριστεί εικόνες.
- Αποστολή αιτήματος στο AI – η εικόνα και η οδηγία αποστέλλονται στη μηχανή AI μέσω του chatRequest, συλλέγοντας το παραγόμενο κείμενο σε πραγματικό χρόνο.
- Εισαγωγή του κειμένου που δημιουργήθηκε από το AI στο έγγραφο – η λειτουργία ανιχνεύει εάν έχει επιλεγεί εικόνα ή όχι και εισάγει το αποτέλεσμα κατάλληλα.
- Χειρισμός σφαλμάτων – η λειτουργία χειρίζεται με ευγένεια ελλείψεις εικόνων, μη υποστηριζόμενα μοντέλα ή απροσδόκητα σφάλματα AI, παρέχοντας σαφή μηνύματα στον χρήστη.
1. Ανάκτηση της επιλεγμένης εικόνας
Στο ONLYOFFICE, οι εικόνες σε ένα έγγραφο αναφέρονται ως σχέδια (drawings). Για να επεξεργαστούμε μια εικόνα που έχει επιλέξει ο χρήστης, χρησιμοποιούμε το API πρόσθετου του ONLYOFFICE:
let imageData = await new Promise((resolve) => {
window.Asc.plugin.executeMethod(
"GetImageDataFromSelection",
[],
function (result) {
resolve(result);
}
);
});
- Το GetImageDataFromSelection είναι μια μέθοδος πρόσθετου του ONLYOFFICE που εξάγει την τρέχουσα επιλεγμένη εικόνα ως συμβολοσειρά κωδικοποιημένη σε base64.
- Το αποτέλεσμα είναι ένα αντικείμενο, τυπικά:
{
"src": "data:image/png;base64,iVBORw0K...",
"width": 600,
"height": 400
}
Αυτή η συμβολοσειρά src περιέχει ολόκληρη την εικόνα σε μορφή Base64, η οποία μπορεί να αποσταλεί απευθείας σε μοντέλα AI που δέχονται δεδομένα εικόνας.
Σημαντικές προϋποθέσεις:
- Εάν δεν έχει επιλεγεί εικόνα, το imageData είναι null.
- Μερικοί χρήστες μπορεί να επιλέξουν placeholder γραφικά ή κενά ορθογώνια. Για παράδειγμα, το ONLYOFFICE χρησιμοποιεί ένα μικρό λευκό ορθογώνιο ως placeholder για κενές εικόνες. Συγκρίνουμε με την αναπαράσταση base64 του για να τα φιλτράρουμε:
const whiteRectangleBase64 = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
if (imageData.src === whiteRectangleBase64) {
console.log("describeImage: Image is white placeholder");
await insertMessage("Παρακαλώ επιλέξτε πρώτα μια έγκυρη εικόνα.");
return;
}
2. Προετοιμασία της εικόνας για AI
Τα μοντέλα AI αναμένουν εικόνες ως URLs ή δεδομένα κωδικοποιημένα σε 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” περιλαμβάνει την ίδια την εικόνα. Η μηχανή AI μπορεί στη συνέχεια να αναλύσει την εικόνα και να δημιουργήσει σχετικό κείμενο.
- detail: “high” είναι μια προαιρετική υποδήλωση για τα μοντέλα να επεξεργάζονται την εικόνα σε πλήρη ανάλυση.
Λογική μετασχηματισμού:
- Το ONLYOFFICE παρέχει το src ως συμβολοσειρά base64.
- Τα μοντέλα AI μπορούν να δεχτούν είτε base64 δεδομένα είτε ένα προσβάσιμο URL. Εδώ, χρησιμοποιούμε base64 απευθείας για να αποφύγουμε τη μεταφόρτωση σε εξωτερικό διακομιστή.
- Τυλίγουμε την εικόνα σε ένα αντικείμενο συμβατό με το API αιτήματος συνομιλίας του AI. Αυτή η δομή επιτρέπει πολλαπλούς τύπους περιεχομένου σε ένα μόνο μήνυμα.
3. Αποστολή του αιτήματος στο AI
Μόλις έχουμε δομημένη την εικόνα και την οδηγία, χρησιμοποιούμε τη μηχανή πρόσθετου AI του ONLYOFFICE:
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 επιτρέπει την αποστολή μηνυμάτων τύπου συνομιλίας, όπου η οδηγία και η εικόνα αναλύονται μαζί.
- Η επανάκληση συλλέγει τμήματα κειμένου απάντησης AI σε πραγματικό χρόνο.
- Πριν την αποστολή, ελέγχουμε εάν το επιλεγμένο μοντέλο AI υποστηρίζει όραση. Μόνο συγκεκριμένα μοντέλα (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(
"⚠ Αυτό το μοντέλο ενδέχεται να μην υποστηρίζει εικόνες. Παρακαλώ επιλέξτε ένα μοντέλο με δυνατότητα όρασης (π.χ. GPT-4V, Gemini, κλπ.)."
);
return;
}
4. Εισαγωγή της εξόδου AI στο έγγραφο
Μετά τη λήψη της εξόδου AI, το κείμενο πρέπει να εισαχθεί πίσω στο έγγραφο ONLYOFFICE. Η λογική χειρίζεται δύο περιπτώσεις:
- Εικόνα επιλεγμένη: Εισαγωγή παραγράφου μετά την εικόνα.
- Καμία επιλεγμένη εικόνα: Εισαγωγή παραγράφου μετά την τρέχουσα θέση του δρομέα.
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) εισάγει το παραγόμενο κείμενο αμέσως μετά την επιλεγμένη εικόνα ή παράγραφο.
- Αυτό εξασφαλίζει απρόσκοπτη ενσωμάτωση: η έξοδος AI εμφανίζεται πάντα στο σωστό πλαίσιο.
5. Χειρισμός ακραίων περιπτώσεων και σφαλμάτων
Ορισμένες προκλήσεις απαιτούσαν επιπλέον προσοχή:
- Καμία επιλεγμένη εικόνα - Προτροπή του χρήστη να επιλέξει μία.
- Μη υποστηριζόμενο μοντέλο AI - Προειδοποίηση του χρήστη πριν από την αποστολή αιτήματος.
- Κενή απόκριση AI - Ειδοποίηση του χρήστη ότι το AI δεν μπόρεσε να δημιουργήσει περιγραφή.
- Απροσδόκητα σφάλματα - Χρήση ένθετων try/catch για ασφαλή τερματισμό τρεχουσών ενεργειών επεξεργαστή:
} catch (e) {
try {
await Asc.Editor.callMethod("EndAction", ["GroupActions"]);
await Asc.Editor.callMethod("EndAction", [
"Block",
"AI (describeImage)",
]);
} catch (ee) {
}
Αυτό εξασφαλίζει ότι το έγγραφο παραμένει σταθερό ακόμη και αν το AI ή το πρόσθετο αποτύχει στη μέση της λειτουργίας.
Τελικό αποτέλεσμα
Η λειτουργία describeImage δείχνει πώς οι προσαρμοσμένες λειτουργίες μπορούν να επεκτείνουν τον πράκτορα AI με μικρούς αλλά υψηλής επίδρασης τρόπους. Συνδυάζοντας σαφείς οδηγίες με λογική ενήμερη του επεξεργαστή, μπορείτε να δημιουργήσετε λειτουργίες που ταιριάζουν απευθείας σε πραγματικές ροές εργασιών αντί για γενικές ενέργειες AI.
Δοκιμάστε να δημιουργήσετε τις δικές σας προσαρμοσμένες λειτουργίες για να προσαρμόσετε τη λειτουργικότητα του πράκτορα AI μας. Εάν δημιουργήσετε κάτι χρήσιμο, μη διστάσετε να το μοιραστείτε μαζί μας μέσω της σελίδας επικοινωνίας.
Δημιουργήστε τον δωρεάν λογαριασμό ONLYOFFICE σας
Online προβολή, επεξεργασία και συνεργασία σε έγγραφα, υπολογιστικά φύλλα, παρουσιάσεις, φόρμες και αρχεία PDF.
