Da ideia à implementação: criando uma função de IA personalizada para descrição de imagens
Com o nosso agente de IA, você pode ir além das ações padrão do editor e adicionar funções personalizadas de acordo com suas necessidades. Esta publicação orienta você na criação da função describeImage e explica como ela transforma imagens em títulos, legendas e texto alternativo acessível.
A ideia
O objetivo é simples. Selecione uma imagem, forneça uma breve instrução e receba o texto gerado exatamente onde você precisa. A função suporta casos de uso comuns, como títulos de imagens, legendas e texto alternativo, evitando suposições sobre a intenção do usuário ao se basear em prompts explícitos.
Projetando a função
Para disponibilizar a função ao mecanismo de IA do ONLYOFFICE, ela foi definida como uma RegisteredFunction. Essa definição especifica o nome da função, os parâmetros esperados e exemplos de prompts que demonstram o uso pretendido.
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.",
},
},
],
});
Esta definição tem dois objetivos:
- Ele informa ao mecanismo de IA do OnlyOffice sobre os recursos da função e a entrada esperada.
- Ele fornece exemplos de uso para orientar tanto a IA quanto os usuários finais.
Implementando a lógica
O método call contém a funcionalidade real executada quando o usuário invoca a função:
- Recuperar a imagem selecionada – usando GetImageDataFromSelection, buscamos a imagem no documento. Também filtramos imagens de espaço reservado para garantir resultados significativos de IA.
- Construa o prompt da IA – a instrução do usuário é combinada com o contexto da imagem selecionada para criar um prompt claro e acionável.
- Verifique a compatibilidade do modelo de IA – apenas modelos com capacidade de visão (como GPT-4V ou Gemini) podem processar imagens. Alertamos o usuário se o modelo atual não for capaz de lidar com imagens.
- Envie a solicitação para a IA – a imagem e o prompt são enviados para o mecanismo de IA por meio do chatRequest, coletando o texto gerado em tempo real.
- Insira texto gerado por IA no documento – a função detecta se uma imagem está selecionada ou não e insere o resultado de forma adequada.
- Tratamento de erros – a função lida com elegância com imagens ausentes, modelos não suportados ou erros inesperados de IA, fornecendo mensagens claras ao usuário.
1. Obter a imagem selecionada
No OnlyOffice, as imagens em um documento são chamadas de drawing. Para processar uma imagem selecionada pelo usuário, usamos a API do plug-in OnlyOffice:
let imageData = await new Promise((resolve) => {
window.Asc.plugin.executeMethod(
"GetImageDataFromSelection",
[],
function (result) {
resolve(result);
}
);
});
- GetImageDataFromSelection é um método do plug-in OnlyOffice que extrai a imagem selecionada no momento como uma string codificada em base64.
- O resultado é um objeto, normalmente:
{
"src": "data:image/png;base64,iVBORw0K...",
"width": 600,
"height": 400
}
Esta string src contém a imagem inteira no formato Base64, que pode ser enviada diretamente para modelos de IA que aceitam dados de imagem.
Considerações importantes:
- Se nenhuma imagem for selecionada, imageData é null.
- Alguns usuários podem selecionar gráficos de espaço reservado ou retângulos vazios. Por exemplo, o OnlyOffice usa um pequeno retângulo branco como espaço reservado para imagens vazias. Comparamos com sua representação base64 para filtrá-los:
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. Preparando a imagem para IA
Os modelos de IA esperam imagens como URLs ou dados codificados em base64, normalmente em um campo como image_url. Em nossa função, passamos a imagem junto com um prompt textual em uma matriz estruturada:
let messages = [
{
role: "user",
content: [
{ type: "text", text: argPrompt },
{
type: "image_url",
image_url: { url: imageData.src, detail: "high" },
},
],
},
];
- type: “text” fornece instruções imediatas (por exemplo, “Adicione uma legenda descritiva”).
- type: “image_url” inclui a própria imagem. O mecanismo de IA pode então analisar a imagem e gerar texto relevante.
- detail: “high” é uma dica opcional para os modelos processarem a imagem em resolução total.
Lógica de transformação:
- O OnlyOffice fornece src como uma string base64.
- Os modelos de IA podem aceitar dados base64 ou uma URL acessível. Aqui, usamos base64 diretamente para evitar o upload para um servidor externo.
- Envolvemos a imagem em um objeto compatível com a API de solicitação de chat da IA. Essa estrutura permite vários tipos de conteúdo em uma única mensagem.
3. Envio da solicitação para a IA
Depois de estruturar a imagem e o prompt, usamos o mecanismo do plugin 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 permite o envio chat-style messages, onde o prompt e a imagem são analisados em conjunto.
- A chamada de retorno coleta trechos do texto da resposta da IA em tempo real.
- Antes do envio, verificamos se o modelo de IA selecionado suporta visão. Apenas determinados modelos (GPT-4V, Gemini) podem processar imagens:
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. Inserindo a saída da IA no documento
Após receber a saída da IA, o texto precisa ser inserido novamente no documento OnlyOffice. A lógica lida com dois casos:
- Image selected: Insira um parágrafo após a imagem.
- No image selected: Insira um parágrafo após a localização atual do cursor.
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() recupera as imagens (desenhos) atualmente selecionadas.
- Api.CreateParagraph() cria um novo objeto de parágrafo.
- InsertParagraph(para, “after”, true) insere o texto gerado imediatamente após a imagem ou o parágrafo selecionado.
- Isso garante uma integração perfeita: a saída da IA sempre aparece no contexto certo.
5. Tratamento de casos extremos e erros
Alguns desafios exigiram atenção especial:
- No image selected – Solicite ao usuário que selecione uma opção.
- Unsupported AI model – Avisar o usuário antes de enviar uma solicitação.
- Empty AI response – Notifique o usuário que a IA não conseguiu gerar uma descrição.
- Unexpected errors – Use try/catch aninhado para encerrar com segurança quaisquer ações em andamento no editor:
} catch (e) {
try {
await Asc.Editor.callMethod("EndAction", ["GroupActions"]);
await Asc.Editor.callMethod("EndAction", [
"Block",
"AI (describeImage)",
]);
} catch (ee) {
}
Isso garante que o documento permaneça estável mesmo que a IA ou o plug-in falhem no meio da operação.
Resultado final
A função describeImage mostra como funções personalizadas podem ampliar o agente de IA de maneiras pequenas, mas de alto impacto. Ao combinar prompts claros com lógica sensível ao editor, você pode criar recursos que se encaixam diretamente em fluxos de trabalho reais, em vez de ações genéricas de IA.
Experimente criar suas próprias funções personalizadas para personalizar a funcionalidade do nosso agente de IA. Se você criar algo útil, sinta-se à vontade para compartilhar conosco através da página de contato.
Crie sua conta gratuita no ONLYOFFICE
Visualize, edite e colabore em documentos, planilhas, slides, formulários e arquivos PDF online.
