De l’idée à la mise en œuvre : création d’une fonction IA personnalisée pour la description d’images
Grâce à notre agent IA, vous pouvez aller au-delà des actions standard de l’éditeur et ajouter des fonctions personnalisées adaptées à vos besoins. Cet article vous guide dans la création de la fonction describeImage et explique comment elle transforme les images en titres, légendes et texte alternatif accessible.
L’idée
L’objectif est simple. Sélectionnez une image, fournissez une brève instruction et recevez le texte généré exactement là où vous en avez besoin. La fonction prend en charge les cas d’utilisation courants tels que les titres d’images, les légendes et le texte alternatif, tout en évitant les suppositions sur l’intention de l’utilisateur en s’appuyant sur des invites explicites.
Conception de la fonction
Pour rendre la fonction disponible pour le moteur d’IA ONLYOFFICE, elle a été définie comme une fonction enregistrée (RegisteredFunction). Cette définition précise le nom de la fonction, les paramètres attendus et des exemples d’invites illustrant l’utilisation prévue.
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.",
},
},
],
});
Cette définition a deux objectifs :
- Il informe le moteur IA d’ONLYOFFICE des capacités de la fonction et des entrées attendues.
- Il fournit des exemples d’utilisation pour guider à la fois l’IA et les utilisateurs finaux.
Mise en œuvre de la logique
La méthode call contient la fonctionnalité réelle exécutée lorsque l’utilisateur invoque la fonction :
- Récupérer l’image sélectionnée : à l’aide de GetImageDataFromSelection, nous récupérons l’image dans le document. Nous filtrons également les images de remplacement afin de garantir des résultats IA pertinents.
- Construire l’invite IA : les instructions de l’utilisateur sont combinées au contexte de l’image sélectionnée afin de créer une invite claire et exploitable.
- Vérifier la compatibilité du modèle IA : seuls les modèles dotés de capacités visuelles (tels que GPT-4V ou Gemini) peuvent traiter les images. Nous alertons l’utilisateur si son modèle actuel ne peut pas traiter les images.
- Envoyer la demande à l’IA : l’image et l’invite sont envoyées au moteur IA via chatRequest, qui collecte le texte généré en temps réel.
- Insérer le texte généré par l’IA dans le document : la fonction détecte si une image est sélectionnée ou non et insère le résultat de manière appropriée.
- Gestion des erreurs : la fonction gère avec élégance les images manquantes, les modèles non pris en charge ou les erreurs IA inattendues, en fournissant des messages clairs à l’utilisateur.
1. Récupération de l’image sélectionnée
Dans ONLYOFFICE, les images d’un document sont appelées dessins. Pour traiter une image sélectionnée par l’utilisateur, nous utilisons l’API du plugin ONLYOFFICE :
let imageData = await new Promise((resolve) => {
window.Asc.plugin.executeMethod(
"GetImageDataFromSelection",
[],
function (result) {
resolve(result);
}
);
});
- GetImageDataFromSelection est une méthode du plugin ONLYOFFICE qui extrait l’image actuellement sélectionnée sous forme de chaîne codée en base64.
- Le résultat est un objet, généralement :
{
"src": "data:image/png;base64,iVBORw0K...",
"width": 600,
"height": 400
}
Cette chaîne src contient l’image entière au format Base64, qui peut être directement envoyée aux modèles d’IA acceptant les données d’image.
Considérations clés :
- Si aucune image n’est sélectionnée, imageData est nul.
- Certains utilisateurs peuvent sélectionner des images de remplacement ou des rectangles vides. Par exemple, ONLYOFFICE utilise un petit rectangle blanc comme image de remplacement pour les images vides. Nous les comparons à leur représentation base64 pour les filtrer :
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. Préparation de l’image pour l’IA
Les modèles d’IA attendent des images sous forme d’URL ou de données encodées en base64, généralement dans un champ tel que image_url. Dans notre fonction, nous transmettons l’image avec une invite textuelle dans un tableau structuré :
let messages = [
{
role: "user",
content: [
{ type: "text", text: argPrompt },
{
type: "image_url",
image_url: { url: imageData.src, detail: "high" },
},
],
},
];
- type : “text” fournit des instructions rapides (par exemple, « Ajouter une légende descriptive »).
- type : “image_url” inclut l’image elle-même. Le moteur d’IA peut ensuite analyser l’image et générer un texte pertinent.
- detail: “high” est une indication facultative permettant aux modèles de traiter l’image en pleine résolution.
Logique de transformation :
- ONLYOFFICE fournit src sous forme de chaîne base64.
- Les modèles d’IA peuvent accepter soit des données base64, soit une URL accessible. Ici, nous utilisons directement base64 pour éviter le téléchargement vers un serveur externe.
- Nous encapsulons l’image dans un objet compatible avec l’API de requête de chat de l’IA. Cette structure permet d’inclure plusieurs types de contenu dans un seul message.
3. Envoi de la demande à l’IA
Une fois que nous avons structuré l’image et l’invite, nous utilisons le moteur du plugin IA :
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 permet d’envoyer des messages de type chat, où l’invite et l’image sont analysées ensemble.
- Le rappel collecte des morceaux de texte de réponse de l’IA en temps réel.
- Avant l’envoi, nous vérifions si le modèle d’IA sélectionné prend en charge la vision. Seuls certains modèles (GPT-4V, Gemini) peuvent traiter les images :
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. Insertion de la sortie IA dans le document
Après avoir reçu la sortie IA, le texte doit être réinséré dans le document ONLYOFFICE. La logique gère deux cas :
- Image sélectionnée : insérer un paragraphe après l’image.
- Aucune image sélectionnée : insérer un paragraphe après l’emplacement actuel du curseur.
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() récupère les images (dessins) actuellement sélectionnées.
- Api.CreateParagraph() crée un nouvel objet paragraphe.
- InsertParagraph(para, « after », true) insère le texte généré immédiatement après l’image ou le paragraphe sélectionné.
- Cela garantit une intégration transparente : la sortie de l’IA apparaît toujours dans le bon contexte.
5. Gestion des cas limites et des erreurs
Certains défis ont nécessité une attention particulière :
- Aucune image sélectionnée – Invitez l’utilisateur à en sélectionner une.
- Modèle d’IA non pris en charge – Avertissez l’utilisateur avant d’envoyer une requête.
- Réponse IA vide – Informez l’utilisateur que l’IA n’a pas pu générer de description.
- Erreurs inattendues – Utilisez une boucle try/catch imbriquée pour mettre fin en toute sécurité à toute action en cours dans l’éditeur :
} catch (e) {
try {
await Asc.Editor.callMethod("EndAction", ["GroupActions"]);
await Asc.Editor.callMethod("EndAction", [
"Block",
"AI (describeImage)",
]);
} catch (ee) {
}
Cela garantit la stabilité du document même en cas de défaillance de l’IA ou du plugin en cours d’opération.
Résultat final
La fonction describeImage montre comment les fonctions personnalisées peuvent étendre l’agent IA de manière modeste mais très efficace. En combinant des invites claires avec une logique sensible à l’éditeur, vous pouvez créer des fonctionnalités qui s’intègrent directement dans des flux de travail réels au lieu d’actions IA génériques.
Essayez de créer vos propres fonctions personnalisées pour personnaliser les fonctionnalités de notre agent IA. Si vous créez quelque chose d’utile, n’hésitez pas à le partager avec nous via la page de contact.
Créez votre compte ONLYOFFICE gratuit
Affichez, modifiez et coéditez des documents texte, feuilles de calcul, diapositives, formulaires et fichiers PDF en ligne.
