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:

typescript
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:

typescript
// 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:

typescript
// 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:

typescript
// 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 lighting

3. Extracción de texto (OCR)#

Extrae y transcribe texto de las imágenes:

typescript
// 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:

typescript
const result = await agent.analyzeImage('/path/to/image.jpg');

Datos en Base64#

Analiza imágenes a partir de datos codificados en base64:

typescript
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:

typescript
const agent = await Agent.create({
  name: 'VisionAgent',
  model: 'gpt-6-astra',
  visionModel: 'gpt-6-astra',  // Specify vision model here
  vision: true
});

Variables de entorno#

bash
# 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 set

El 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:

typescript
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#

typescript
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#

typescript
// 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#

typescript
// 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#

FuncionalidadOpenAI (gpt-4o)Claude (claude-sonnet-5)Gemini (gemini-1.5-pro)Ollama (llava)
Calidad de análisisExcelenteExcelenteExcelenteBuena
Velocidad de procesamientoRápidaRápidaRápidaVariable
CostePago por usoPago por usoPago por usoGratis (local)
PrivacidadEn la nubeEn la nubeEn la nubeProcesamiento local
Niveles de detalleBajo/Alto/AutoEstándarEstándarEstándar
Soporte de idiomasExtensoExtensoExtensoBueno

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 visionModel de forma explícita, por ejemplo claude-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:

typescript
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 imagen
    • prompt (string, opcional): prompt de análisis personalizado
    • detail (string, opcional): nivel de detalle 'low' o 'high'

describe_image#

  • Parámetros:
    • image_path (string, obligatorio): ruta al archivo de imagen
    • style (string, opcional): estilo de descripción ('detailed', 'concise', 'accessibility', 'technical')

extract_text_from_image#

  • Parámetros:
    • image_path (string, obligatorio): ruta al archivo de imagen
    • language (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:

typescript
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:

typescript
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:

typescript
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:

typescript
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."