Visión
Análisis de imágenes y procesamiento de documentos para interacciones multimodales
Descripción general#
El sistema Vision permite que los agentes procesen y analicen imágenes, proporcionando capacidades de IA multimodal para interacciones más ricas. Soporta múltiples formatos de imagen, ofrece varios modos de análisis y se integra sin problemas con los proveedores OpenAI, Claude, Gemini y Ollama local para opciones de despliegue flexibles.
Habilitar la visión#
Habilita las capacidades de visión para un agente estableciendo la opción vision en true:
import { Agent } from '@astreus-ai/astreus';
const agent = await Agent.create({
name: 'VisionAgent',
model: 'gpt-6-astra', // Vision-capable model
vision: true // Enable vision capabilities (default: false)
});Sistema de archivos adjuntos#
Astreus soporta un sistema de archivos adjuntos intuitivo para trabajar con imágenes:
// Clean, modern attachment API
const response = await agent.ask("What do you see in this image?", {
attachments: [
{ type: 'image', path: '/path/to/image.jpg', name: 'My Photo' }
]
});El sistema de archivos adjuntos automáticamente:
- Detecta el tipo de archivo y selecciona las herramientas adecuadas
- Enriquece el prompt con información del adjunto
- Habilita el uso de herramientas cuando hay adjuntos presentes
Capacidades de visión#
El sistema de visión ofrece tres capacidades principales a través de herramientas integradas:
1. Análisis general de imágenes#
Analiza imágenes con prompts personalizados y niveles de detalle configurables:
// Using attachments (recommended approach)
const response = await agent.ask("Please analyze this screenshot and describe the UI elements", {
attachments: [
{ type: 'image', path: '/path/to/screenshot.png', name: 'UI Screenshot' }
]
});
// Using the analyze_image tool through conversation
const response2 = await agent.ask("Please analyze the image at /path/to/screenshot.png and describe the UI elements");
// Direct method call
const analysis = await agent.analyzeImage('/path/to/image.jpg', {
prompt: 'What UI elements are visible in this interface?',
detail: 'high',
maxTokens: 1500
});2. Descripción de imágenes#
Genera descripciones estructuradas para diferentes casos de uso:
// Accessibility-friendly description
const description = await agent.describeImage('/path/to/image.jpg', 'accessibility');
// Available styles:
// - 'detailed': Comprehensive description of all visual elements
// - 'concise': Brief description of main elements
// - 'accessibility': Screen reader-friendly descriptions
// - 'technical': Technical analysis including composition and lighting3. Extracción de texto (OCR)#
Extrae y transcribe texto de las imágenes:
// Extract text with language hint
const text = await agent.extractTextFromImage('/path/to/document.jpg', 'english');
// The system maintains original formatting and structure
console.log(text);Formatos soportados#
El sistema de visión soporta estos formatos de imagen:
- JPEG (
.jpg,.jpeg) - PNG (
.png) - GIF (
.gif) - BMP (
.bmp) - WebP (
.webp)
Fuentes de entrada#
Rutas de archivo#
Analiza imágenes desde el sistema de archivos local:
const result = await agent.analyzeImage('/path/to/image.jpg');Datos en Base64#
Analiza imágenes a partir de datos codificados en base64:
const base64Image = 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...';
const result = await agent.analyzeImageFromBase64(base64Image);Configuración#
Configuración del modelo de visión#
Especifica el modelo de visión directamente en la configuración del agente:
const agent = await Agent.create({
name: 'VisionAgent',
model: 'gpt-6-astra',
visionModel: 'gpt-6-astra', // Specify vision model here
vision: true
});Variables de entorno#
# API keys (auto-detected based on model)
OPENAI_API_KEY=your_openai_key # For OpenAI models
OPENAI_VISION_API_KEY=your_openai_key # Dedicated vision API key (takes priority)
ANTHROPIC_API_KEY=your_anthropic_key # For Claude models
ANTHROPIC_VISION_API_KEY=your_anthropic_key # Dedicated vision API key (takes priority)
GEMINI_API_KEY=your_gemini_key # For Gemini models
GEMINI_VISION_API_KEY=your_gemini_key # Dedicated vision API key (takes priority)
# Ollama configuration (local)
OLLAMA_BASE_URL=http://localhost:11434 # Default if not setEl sistema de visión selecciona automáticamente el proveedor adecuado según el visionModel especificado en la configuración del agente.
Opciones de análisis#
Configura el comportamiento del análisis con estas opciones:
interface AnalysisOptions {
prompt?: string; // Custom analysis prompt
maxTokens?: number; // Response length limit (default: 1000)
detail?: 'low' | 'high' | 'auto'; // Analysis detail level (OpenAI only)
}Ejemplos de uso#
Análisis de capturas de pantalla#
const agent = await Agent.create({
name: 'UIAnalyzer',
model: 'gpt-6-astra',
vision: true
});
// Analyze a UI screenshot
const analysis = await agent.analyzeImage('/path/to/app-screenshot.png', {
prompt: 'Analyze this mobile app interface. Identify key UI components, layout structure, and potential usability issues.',
detail: 'high'
});
console.log(analysis);Procesamiento de documentos#
// Extract text from scanned documents
const documentText = await agent.extractTextFromImage('/path/to/scanned-invoice.jpg', 'english');
// Generate accessible descriptions
const accessibleDesc = await agent.describeImage('/path/to/chart.png', 'accessibility');Conversaciones multimodales#
// Using attachments for cleaner API
const response = await agent.ask("I'm getting an error. Can you analyze this screenshot and help me fix it?", {
attachments: [
{ type: 'image', path: '/Users/john/Desktop/error.png', name: 'Error Screenshot' }
]
});
// Multiple attachments
const response2 = await agent.ask("Compare these UI mockups and suggest improvements", {
attachments: [
{ type: 'image', path: '/designs/mockup1.png', name: 'Design A' },
{ type: 'image', path: '/designs/mockup2.png', name: 'Design B' }
]
});
// Traditional approach (still works)
const response3 = await agent.ask(
"Please analyze the error screenshot at /Users/john/Desktop/error.png and suggest how to fix the issue"
);Comparación de proveedores#
| Funcionalidad | OpenAI (gpt-4o) | Claude (claude-sonnet-5) | Gemini (gemini-1.5-pro) | Ollama (llava) |
|---|---|---|---|---|
| Calidad de análisis | Excelente | Excelente | Excelente | Buena |
| Velocidad de procesamiento | Rápida | Rápida | Rápida | Variable |
| Coste | Pago por uso | Pago por uso | Pago por uso | Gratis (local) |
| Privacidad | En la nube | En la nube | En la nube | Procesamiento local |
| Niveles de detalle | Bajo/Alto/Auto | Estándar | Estándar | Estándar |
| Soporte de idiomas | Extenso | Extenso | Extenso | Bueno |
Proveedor OpenAI#
- Ideal para: aplicaciones en producción que requieren alta precisión
- Modelo por defecto:
gpt-4o-mini - Funciones: control del nivel de detalle, excelente reconocimiento de texto
Proveedor Claude#
- Ideal para: análisis matizado y descripciones detalladas
- Modelo por defecto: Ninguno. Define
visionModelde forma explícita, por ejemploclaude-sonnet-5 - Funciones: fuerte razonamiento, excelente comprensión del contexto
Proveedor Gemini#
- Ideal para: tareas multimodales y análisis de documentos
- Modelo por defecto:
gemini-1.5-pro - Funciones: soporte de contexto largo, adecuado para imágenes complejas
Proveedor Ollama (local)#
- Ideal para: aplicaciones sensibles a la privacidad o desarrollo
- Modelo por defecto:
llava - Funciones: procesamiento local, sin costes de API, capacidad sin conexión
Procesamiento por lotes#
Procesa múltiples imágenes de forma eficiente:
const images = [
'/path/to/image1.jpg',
'/path/to/image2.png',
'/path/to/image3.gif'
];
// Process all images in parallel
const results = await Promise.all(
images.map(imagePath =>
agent.describeImage(imagePath, 'concise')
)
);
console.log('Analysis results:', results);
// Or use task attachments for batch processing
const batchTask = await agent.createTask({
prompt: 'Analyze all these images and provide a comparative report',
attachments: images.map(path => ({
type: 'image',
path,
name: path.split('/').pop()
}))
});
const batchResult = await agent.executeTask(batchTask.id);Herramientas de visión integradas#
Cuando la visión está habilitada, estas herramientas están disponibles automáticamente:
analyze_image#
- Parámetros:
image_path(string, obligatorio): ruta al archivo de imagenprompt(string, opcional): prompt de análisis personalizadodetail(string, opcional): nivel de detalle 'low' o 'high'
describe_image#
- Parámetros:
image_path(string, obligatorio): ruta al archivo de imagenstyle(string, opcional): estilo de descripción ('detailed', 'concise', 'accessibility', 'technical')
extract_text_from_image#
- Parámetros:
image_path(string, obligatorio): ruta al archivo de imagenlanguage(string, opcional): indicación de idioma para mejorar la precisión del OCR
Tipos de respuesta#
Los métodos de visión devuelven respuestas en forma de cadena con los resultados del análisis.
Respuesta de analyze_image#
El análisis de imágenes devuelve una cadena descriptiva basada en tu prompt:
const analysis = await agent.analyzeImage('/path/to/office.jpg', {
prompt: "What objects are in this image and how is the space organized?",
detail: "high"
});
// Response: string
"The image shows a modern office workspace with a MacBook Pro laptop, wireless keyboard, and mouse on a wooden desk. To the left is a coffee mug and a notebook. The desk is positioned near a window with natural lighting. The space features a minimalist organization with cable management and a small potted plant."Respuesta de describeImage#
Describeimage devuelve una cadena de descripción formateada:
const description = await agent.describeImage('/path/to/product.jpg');
// Response: string
"A professional product photograph featuring a stainless steel water bottle with a matte black finish. The bottle has a wide mouth opening and is photographed against a white background with soft studio lighting creating subtle highlights along the curved surfaces."Respuesta de extractTextFromImage#
El OCR devuelve el texto extraído como una cadena:
const text = await agent.extractTextFromImage('/path/to/document.png', {
language: 'en'
});
// Response: string
"INVOICE\nDate: January 15, 2024\nInvoice #: INV-2024-001\n\nBill To:\nAcme Corporation\n123 Main Street\nNew York, NY 10001\n\nDescription Quantity Price Total\nProfessional Services 8 hrs $150 $1,200\nConsulting Fee 1 $500 $500\n\nSubtotal: $1,700\nTax (8%): $136\nTotal: $1,836"Respuesta de análisis de imagen desde Base64#
El análisis de imágenes en base64 también devuelve una cadena:
const base64Image = "data:image/png;base64,iVBORw0KG...";
const result = await agent.analyzeImageFromBase64(base64Image, {
prompt: "Identify the main subject and mood of this image"
});
// Response: string
"The main subject is a sunset landscape with mountains in the background. The mood is serene and peaceful, with warm orange and pink tones dominating the sky. The composition creates a sense of tranquility and natural beauty."