비전

멀티모달 상호작용을 위한 이미지 분석 및 문서 처리

Overview#

비전 시스템을 사용하면 에이전트가 이미지를 처리하고 분석할 수 있어, 더 풍부한 상호작용을 위한 멀티모달 AI 기능을 제공합니다. 여러 이미지 형식을 지원하고, 다양한 분석 모드를 제공하며, 유연한 배포 옵션을 위해 OpenAI, Claude, Gemini, 로컬 Ollama 프로바이더와 원활하게 통합됩니다.

Enabling Vision#

vision 옵션을 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)
});

Attachment System#

Astreus는 이미지를 다루기 위한 직관적인 첨부 시스템을 지원합니다.

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' }
  ]
});

첨부 시스템은 자동으로:

  • 파일 타입을 감지하고 적절한 도구를 선택합니다
  • 첨부 정보로 프롬프트를 강화합니다
  • 첨부 파일이 있을 때 도구 사용을 활성화합니다

Vision Capabilities#

비전 시스템은 내장 도구를 통해 세 가지 핵심 기능을 제공합니다.

1. General Image Analysis#

커스텀 프롬프트와 설정 가능한 상세 수준으로 이미지를 분석합니다.

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. Image Description#

다양한 사용 사례를 위한 구조화된 설명을 생성합니다.

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. Text Extraction (OCR)#

이미지에서 텍스트를 추출하고 옮겨 적습니다.

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);

Supported Formats#

비전 시스템은 다음 이미지 형식을 지원합니다.

  • JPEG (.jpg, .jpeg)
  • PNG (.png)
  • GIF (.gif)
  • BMP (.bmp)
  • WebP (.webp)

Input Sources#

File Paths#

로컬 파일 시스템에서 이미지를 분석합니다.

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

Base64 Data#

base64로 인코딩된 데이터에서 이미지를 분석합니다.

typescript
const base64Image = 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...';
const result = await agent.analyzeImageFromBase64(base64Image);

Configuration#

Vision Model Configuration#

에이전트 설정에서 직접 비전 모델을 지정하세요.

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

Environment Variables#

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

비전 시스템은 에이전트 설정에 지정된 visionModel에 따라 적절한 프로바이더를 자동으로 선택합니다.

Analysis Options#

다음 옵션으로 분석 동작을 설정하세요.

typescript
interface AnalysisOptions {
  prompt?: string;                    // Custom analysis prompt
  maxTokens?: number;                 // Response length limit (default: 1000)
  detail?: 'low' | 'high' | 'auto';   // Analysis detail level (OpenAI only)
}

Usage Examples#

Screenshot Analysis#

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);

Document Processing#

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');

Multimodal Conversations#

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"
);

Provider Comparison#

FeatureOpenAI (gpt-4o)Claude (claude-sonnet-5)Gemini (gemini-1.5-pro)Ollama (llava)
Analysis QualityExcellentExcellentExcellentGood
Processing SpeedFastFastFastVariable
CostPay-per-usePay-per-usePay-per-useFree (local)
PrivacyCloud-basedCloud-basedCloud-basedLocal processing
Detail LevelsLow/High/AutoStandardStandardStandard
Language SupportExtensiveExtensiveExtensiveGood

OpenAI Provider#

  • 적합한 대상: 높은 정확도가 필요한 프로덕션 애플리케이션
  • Default Model: gpt-4o-mini
  • Features: 상세 수준 제어, 뛰어난 텍스트 인식

Claude Provider#

  • 적합한 대상: 미묘한 분석과 상세한 설명
  • Default Model: 없음. visionModel을 명시적으로 지정하세요(예: claude-sonnet-5)
  • Features: 강력한 추론, 뛰어난 맥락 이해

Gemini Provider#

  • 적합한 대상: 멀티모달 작업과 문서 분석
  • Default Model: gemini-1.5-pro
  • Features: 긴 컨텍스트 지원, 복잡한 이미지에 적합

Ollama Provider (Local)#

  • 적합한 대상: 개인정보 보호가 중요한 애플리케이션이나 개발 환경
  • Default Model: llava
  • Features: 로컬 처리, API 비용 없음, 오프라인 사용 가능

Batch Processing#

여러 이미지를 효율적으로 처리하세요.

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);

Built-in Vision Tools#

비전이 활성화되면 다음 도구를 자동으로 사용할 수 있습니다.

analyze_image#

  • Parameters:
    • image_path (string, required): 이미지 파일 경로
    • prompt (string, optional): 커스텀 분석 프롬프트
    • detail (string, optional): 'low' 또는 'high' 상세 수준

describe_image#

  • Parameters:
    • image_path (string, required): 이미지 파일 경로
    • style (string, optional): 설명 스타일 ('detailed', 'concise', 'accessibility', 'technical')

extract_text_from_image#

  • Parameters:
    • image_path (string, required): 이미지 파일 경로
    • language (string, optional): 더 나은 OCR 정확도를 위한 언어 힌트

Response Types#

비전 메서드는 분석 결과를 담은 문자열 응답을 반환합니다.

Analyze Image Response#

이미지 분석은 프롬프트를 기반으로 한 설명 문자열을 반환합니다.

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

Describe Image Response#

describeImage는 형식화된 설명 문자열을 반환합니다.

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

Extract Text from Image Response#

OCR은 추출된 텍스트를 문자열로 반환합니다.

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"

Analyze Image from Base64 Response#

base64 이미지 분석도 문자열을 반환합니다.

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