비전
멀티모달 상호작용을 위한 이미지 분석 및 문서 처리
Overview#
비전 시스템을 사용하면 에이전트가 이미지를 처리하고 분석할 수 있어, 더 풍부한 상호작용을 위한 멀티모달 AI 기능을 제공합니다. 여러 이미지 형식을 지원하고, 다양한 분석 모드를 제공하며, 유연한 배포 옵션을 위해 OpenAI, Claude, Gemini, 로컬 Ollama 프로바이더와 원활하게 통합됩니다.
Enabling Vision#
vision 옵션을 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)
});Attachment System#
Astreus는 이미지를 다루기 위한 직관적인 첨부 시스템을 지원합니다.
// 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#
커스텀 프롬프트와 설정 가능한 상세 수준으로 이미지를 분석합니다.
// 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#
다양한 사용 사례를 위한 구조화된 설명을 생성합니다.
// 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. Text Extraction (OCR)#
이미지에서 텍스트를 추출하고 옮겨 적습니다.
// 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#
로컬 파일 시스템에서 이미지를 분석합니다.
const result = await agent.analyzeImage('/path/to/image.jpg');Base64 Data#
base64로 인코딩된 데이터에서 이미지를 분석합니다.
const base64Image = 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...';
const result = await agent.analyzeImageFromBase64(base64Image);Configuration#
Vision Model Configuration#
에이전트 설정에서 직접 비전 모델을 지정하세요.
const agent = await Agent.create({
name: 'VisionAgent',
model: 'gpt-6-astra',
visionModel: 'gpt-6-astra', // Specify vision model here
vision: true
});Environment Variables#
# 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#
다음 옵션으로 분석 동작을 설정하세요.
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#
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#
// 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#
// 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#
| Feature | OpenAI (gpt-4o) | Claude (claude-sonnet-5) | Gemini (gemini-1.5-pro) | Ollama (llava) |
|---|---|---|---|---|
| Analysis Quality | Excellent | Excellent | Excellent | Good |
| Processing Speed | Fast | Fast | Fast | Variable |
| Cost | Pay-per-use | Pay-per-use | Pay-per-use | Free (local) |
| Privacy | Cloud-based | Cloud-based | Cloud-based | Local processing |
| Detail Levels | Low/High/Auto | Standard | Standard | Standard |
| Language Support | Extensive | Extensive | Extensive | Good |
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#
여러 이미지를 효율적으로 처리하세요.
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#
이미지 분석은 프롬프트를 기반으로 한 설명 문자열을 반환합니다.
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는 형식화된 설명 문자열을 반환합니다.
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은 추출된 텍스트를 문자열로 반환합니다.
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 이미지 분석도 문자열을 반환합니다.
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."