ABBYY Phoenix Plus está disponible en ABBYY Vantage Cloud y requiere un derecho de uso contratado. Para habilitarlo en su tenant, póngase en contacto con su ABBYY account team. Para obtener una visión general, consulte LLMs en ABBYY Vantage.
Antes de comenzar
- El derecho de uso de Phoenix Plus está habilitado para su tenant y la conexión ABBYY Phoenix Model aparece en ADMIN → Configuration → Connections.
- Cuenta con una Habilidad de proceso que incluye una actividad personalizada. Para conocer los pasos, consulte Actividad personalizada.
- En la pestaña Available Files de la actividad, seleccione los formatos de exportación que requiere su script. La mayoría de los scripts necesitan OcrJson. Para enviar imágenes de página, también se requiere una exportación en JPEG, que debe generarse antes de que se ejecute la actividad.
Crear una sesión de chat
Llame aContext.CreateLlmChatSession() sin argumentos para abrir una sesión con la conexión gestionada por ABBYY de su tenant. Si indica el nombre de una conexión, la sesión se abrirá con una de las conexiones propias de su tenant.
Propiedades de la sesión
LastUsage y TotalUsage son objetos que incluyen PromptTokens, CompletionTokens y TotalTokens.
Restablecer una sesión
Reset() borra el historial de la conversación y los archivos adjuntos pendientes, de modo que el siguiente mensaje empiece de cero. Se conservan los ajustes como SystemPrompt y Temperature, así como el uso acumulado.
Adjuntar contenido a un mensaje
Adjunte los datos de transacción que desea que vea el modelo y, a continuación, envíelos.
Los archivos adjuntos se ponen en cola para el siguiente mensaje del usuario en lugar de enviarse de inmediato.
También puede crear un historial de conversación sin enviar nada, lo que resulta útil para el aprendizaje con pocos ejemplos:
No existen
AttachFile, AttachBinary ni un Attach genérico. Use los métodos anteriores.Adjuntar las imágenes de página en el orden de las páginas
Los exports JPEG se ordenan segúnProperties["PageIndex"], por lo que adjuntarlos en el orden en que aparecen mantiene la secuencia de los adjuntos alineada con los números de página que indica el modelo.
Enviar el mensaje y leer la respuesta
SendJson devuelve un objeto. Si devuelve una cadena, significa que el modelo no generó un JSON analizable; en ese caso, conviene precisar más el prompt en lugar de reintentar la llamada.
Compruebe cómo finalizó la respuesta
LeaLastFinishReason antes de confiar en una respuesta. El valor "length" indica que la respuesta se truncó al alcanzar el límite de tokens. Esto no es un error y no hay ningún otro indicio, por lo que un script que lo ignore interpretará un resultado parcial como si estuviera completo. La solución consiste en aumentar MaxTokens o reducir el conjunto de campos.
Valide la estructura antes de escribir los valores
Una respuesta puede llegar completa y, aun así, ser estructuralmente incorrecta: con los campos escalares correctos, pero sin nada del contenido repetible que define una skill. Compruebe que la respuesta incluya las tablas y los campos repetibles que solicitó y, si no es así, vuelva a preguntar en lugar de escribir la respuesta en el documento sin verificarla. Reinicie la sesión entre intentos y, después, vuelva a establecerSystemPrompt.
Qué requiere la conexión gestionada
Contexto de documento. La conexión gestionada se rechaza en las ejecuciones que no tengan páginas de documento. De este modo se evita que la credencial compartida de la plataforma se utilice como una pasarela de LLM de uso general. Una actividad personalizada que se ejecuta sobre una transacción con documentos cumple este requisito; un script que abre una sesión fuera de ese contexto, no. Medición. Las llamadas realizadas a través de la conexión gestionada se contabilizan con cargo a su derecho de uso de ABBYY. En cambio, las llamadas que pasan por una conexión configurada por usted mismo se facturan a través de su propio provider. Tenga en cuenta el volumen antes de dirigir un trabajo de reprocesamiento masivo a la conexión gestionada.Límites de los mensajes
Ambos límites se aplican, y todo mensaje que supere cualquiera de ellos se rechaza de inmediato. Calcule el tamaño del mensaje en el script antes de enviarlo, en lugar de dejar que la llamada falle.
El límite máximo del prompt no es un valor fijo único. Se configura por entorno y aumenta con el número de páginas que se procesan, hasta un máximo. Actualmente, en ABBYY Vantage Cloud cada página permite 500 000 caracteres, contabilizados sobre un máximo de tres páginas, hasta un tope de 1 500 000:
Dado que este tope se configura por entorno y puede cambiar, considere estas cifras como informativas y no como un compromiso. Calcule el tamaño del mensaje en tiempo de ejecución y degrade el comportamiento cuando no quepa, en lugar de dar por sentado un presupuesto fijo.
Superarlo produce un mensaje con el siguiente formato:
Errores que no se resuelven reintentando
Un error de envío que mencioneexceeds the maximum allowed size, maximum number of attachments, context length o too large es definitivo. El mensaje es demasiado grande o contiene demasiada información, por lo que la misma llamada volverá a fallar. Las soluciones son reducir la resolución de exportación JPEG, enviar menos páginas o prescindir de las imágenes y ejecutar el proceso únicamente con el JSON de OCR.
Errores que su script no puede capturar
La mayoría de los fallos se pueden capturar en el script contry/catch: problemas de conexión, una solicitud fallida, una respuesta que no es JSON válido o un prompt que supera el límite de tamaño. Gestione esos casos y continúe.
Superar el límite de solicitudes es otra cosa. Existe un límite en la cantidad de llamadas al LLM que puede realizar una misma ejecución del script, ajustado según el número de páginas de la transacción. Superarlo detiene el script con un error de restricción que un try/catch no puede absorber, igual que ocurre con el límite existente de solicitudes HTTP.
Esto es importante si realiza reintentos. Un bucle de validación y nueva consulta consume una llamada cada vez que se ejecuta, y un bucle sin un límite propio acabará alcanzando un límite que no podrá gestionar. Acote sus reintentos.
Envío de imágenes de página
Las imágenes de página funcionan, dentro de un límite práctico que fija el presupuesto del prompt. Dos ejemplos medidos, frente a los límites anteriores:- Una sola imagen de página de 1584x1000 ocupa aproximadamente 311.776 caracteres base64 y unos 2.015 tokens de prompt. En una transacción de una página, eso cabe dentro del margen de 500.000 caracteres y deja espacio para el JSON del OCR y el prompt.
- Un formulario A4 de dos páginas escaneado a 300 dpi genera aproximadamente 1.326.136 caracteres de imagen. Una transacción de dos páginas permite 1.000.000, por lo que se rechaza. Enviarlo como imágenes exigiría reducir cada página a una cuarta parte de su tamaño a 300 dpi.
- Envíe el JSON del OCR como carga útil principal y añada imágenes de página solo para aquello que el text layer no puede transmitir, como sellos, firmas y fotografías.
- Mida el mensaje antes de enviarlo. Si las imágenes no caben, descártelas y reconstruya el prompt en consecuencia, de modo que el documento se siga procesando únicamente con el JSON del OCR.
- Reserve espacio para el JSON del OCR al dimensionar las imágenes, para que una imagen grande no desplace la carga útil de la que se copian sus coordenadas.
- Reduzca la image resolution antes de la exportación cuando el modelo solo necesite ver el layout o un sello, y no el detalle fino.
Ubicaciones y cuadros delimitadores
Cuando se le pide que devuelva coordenadas a partir de la imagen de una página, el modelo devuelve valores sobre una retícula de diez unidades: todos los números son múltiplos de diez, las alturas son uniformes y dos campos distintos comparten un rectángulo idéntico. Se trata de un diseño compuesto, no medido, y ninguna configuración de convención de coordenadas lo corrige. En su lugar, tome la geometría de la capa de OCR de Vantage. La exportación JSON del OCR incluye posiciones medidas tanto del contenido textual como del no textual, incluidoslayout.pages[].pictures[] y barcodes[], de modo que una fotografía, un logotipo o un código de barras se pueden localizar con la misma fiabilidad que una palabra.
Un script robusto:
- Copia las coordenadas; nunca las estima. Cada rectángulo procede de un valor de posición del JSON del OCR, validado frente al tamaño de página del OCR y escalado a la imagen de página de Vantage cuando ambos difieren.
- Exige la procedencia. Cada region que devuelve el modelo se contrasta con la geometría del OCR antes de aceptarse. Se rechaza toda region que no pueda rastrearse hasta la capa de OCR, aunque se conserva el valor extraído.
- Requiere la atribución de página. En un documento multipágina, se rechaza toda region que llegue sin número de página en lugar de asignarla por defecto a la página 1.
Establezca MaxTokens de forma deliberada
DejarMaxTokens con el valor predeterminado del provider expone el proceso a truncamientos silenciosos en documentos densos, detectables únicamente mediante LastFinishReason. Defínalo de forma explícita para que el límite sea suyo y quede claro.
Como referencia de escala, extraer una tabla de nueve columnas celda por celda a lo largo de tres páginas consume aproximadamente 28.000 tokens de finalización.
Conceda tiempo suficiente
La latencia aumenta en función de los tokens de salida generados, no del tamaño de la entrada. Phoenix Plus genera aproximadamente 100 tokens de finalización por segundo, de modo que una respuesta de 28 000 tokens tarda varios minutos.Timeout se define en minutos y está limitado por el tiempo de espera para la ejecución de scripts. Un tiempo de espera de dos minutos aplicado a un documento que requiere 28 000 tokens de salida fallará a los 121 segundos aproximadamente, tras haber generado solo una fracción de la respuesta.