VLM(Vision Chat) スキル

このスキルは z-ai-web-dev-sdk パッケージを使用したビジョンチャット機能の実装を説明し、AI モデルがテキストプロンプトと組み合わせて画像を理解し、応答できるようにします。

スキルパス

スキル場所: {project_path}/skills/VLM

このスキルはプロジェクト内の上記パスに配置されています。

参考スクリプト: 例のテストスクリプトは {Skill Location}/scripts/ ディレクトリで利用可能です。動作例については {Skill Location}/scripts/vlm.ts を参照してください。

概要

Vision Chat を使用すると、画像を分析し、ビジュアルコンテンツから情報を抽出し、自然言語会話を通じて画像について質問に答えることができるアプリケーションを構築できます。

重要: z-ai-web-dev-sdk はバックエンドコードでのみ使用する必要があります。クライアント側コードでは絶対に使用しないでください。

前提条件

z-ai-web-dev-sdk パッケージはすでにインストールされています。以下の例に示すようにインポートしてください。

CLI 使用法 (シンプルなタスク向け)

シンプルな画像分析タスクの場合、コードを記述する代わりに z-ai CLI を使用できます。これは画像の説明のテスト、ビジョン機能のテスト、またはシンプルな自動化に最適です。

基本的な画像分析

# URL から画像を記述する
z-ai vision --prompt "この画像に何が写っていますか？" --image "https://example.com/photo.jpg"

# 短いオプションを使用
z-ai vision -p "この画像を説明してください" -i "https://example.com/image.png"

ローカル画像を分析

# ローカル画像ファイルを分析
z-ai vision -p "この写真にはどんなオブジェクトが写っていますか？" -i "./photo.jpg"

# レスポンスをファイルに保存
z-ai vision -p "シーンを説明してください" -i "./landscape.png" -o description.json

複数の画像

# 複数の画像を一度に分析
z-ai vision \
  -p "この 2 つの画像を比較してください" \
  -i "./photo1.jpg" \
  -i "./photo2.jpg" \
  -o comparison.json

# 詳細分析を含む複数の画像
z-ai vision \
  --prompt "これらの画像の違いは何ですか？" \
  --image "https://example.com/before.jpg" \
  --image "https://example.com/after.jpg"

思考機能付き (Chain of Thought)

# 複雑なビジュアル推論のための思考を有効化
z-ai vision \
  -p "この画像に写っている人の数を数え、彼らの活動を説明してください" \
  -i "./crowd.jpg" \
  --thinking \
  -o analysis.json

ストリーミング出力

# ビジョン分析をストリーミング
z-ai vision -p "この画像を詳細に説明してください" -i "./photo.jpg" --stream

CLI パラメータ

• --prompt, -p <text>: 必須 - 画像についての質問または指示
• --image, -i <URL またはパス>: オプション - 画像 URL またはローカルファイルパス (複数回使用可)
• --thinking, -t: オプション - Chain-of-thought 推論を有効化 (デフォルト: 無効)
• --output, -o <path>: オプション - 出力ファイルパス (JSON 形式)
• --stream: オプション - リアルタイムでレスポンスをストリーミング

サポートされている画像形式

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

CLI vs SDK の使い分け

CLI を使用する場合:

• クイック画像分析
• ビジョンモデル機能のテスト
• 1 回限りの画像説明
• シンプルな自動化スクリプト

SDK を使用する場合:

• 画像を使用したマルチターン会話
• アプリケーション内の動的画像分析
• カスタムロジック付きのバッチ処理
• 複雑なワークフローを持つプロダクション アプリケーション

推奨アプローチ

より優れたパフォーマンスと信頼性のために、画像をモデルに渡すときに画像 URL の代わりに base64 エンコーディングを使用してください。

サポートされているコンテンツタイプ

Vision Chat API は 3 種類のメディアコンテンツをサポートしています:

1. image_url - 画像ファイル向け

静止画 (PNG、JPEG、GIF、WebP など) に対してこのタイプを使用します

{
    role: 'user',
    content: [
        { type: 'text', text: prompt },
        { type: 'image_url', image_url: { url: imageUrl } }
    ]
}

2. video_url - ビデオファイル向け

ビデオコンテンツ (MP4、AVI、MOV など) に対してこのタイプを使用します

{
    role: 'user',
    content: [
        { type: 'text', text: prompt },
        { type: 'video_url', video_url: { url: videoUrl } }
    ]
}

3. file_url - ドキュメントファイル向け

ドキュメントファイル (PDF、DOCX、TXT など) に対してこのタイプを使用します

{
    role: 'user',
    content: [
        { type: 'text', text: prompt },
        { type: 'file_url', file_url: { url: fileUrl } }
    ]
}

注意: 1 つのメッセージで複数のコンテンツタイプを組み合わせることができます。たとえば、テキストと複数の画像、またはテキストと画像とドキュメントの両方を含めることができます。

基本的な Vision Chat 実装

単一画像の分析

import ZAI from 'z-ai-web-dev-sdk';

async function analyzeImage(imageUrl, question) {
  const zai = await ZAI.create();

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          {
            type: 'text',
            text: question
          },
          {
            type: 'image_url',
            image_url: {
              url: imageUrl
            }
          }
        ]
      }
    ],
    thinking: { type: 'disabled' }
  });

  return response.choices[0]?.message?.content;
}

// 使用方法
const result = await analyzeImage(
  'https://example.com/product.jpg',
  'この製品を詳細に説明してください'
);
console.log('分析:', result);

複数画像の分析

import ZAI from 'z-ai-web-dev-sdk';

async function compareImages(imageUrls, question) {
  const zai = await ZAI.create();

  const content = [
    {
      type: 'text',
      text: question
    },
    ...imageUrls.map(url => ({
      type: 'image_url',
      image_url: { url }
    }))
  ];

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: content
      }
    ],
    thinking: { type: 'disabled' }
  });

  return response.choices[0]?.message?.content;
}

// 使用方法
const comparison = await compareImages(
  [
    'https://example.com/before.jpg',
    'https://example.com/after.jpg'
  ],
  'これら 2 つの画像を比較し、違いを説明してください'
);

Base64 画像サポート

import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';

async function analyzeLocalImage(imagePath, question) {
  const zai = await ZAI.create();

  // 画像ファイルを読み込み、base64 に変換
  const imageBuffer = fs.readFileSync(imagePath);
  const base64Image = imageBuffer.toString('base64');
  const mimeType = imagePath.endsWith('.png') ? 'image/png' : 'image/jpeg';

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          {
            type: 'text',
            text: question
          },
          {
            type: 'image_url',
            image_url: {
              url: `data:${mimeType};base64,${base64Image}`
            }
          }
        ]
      }
    ],
    thinking: { type: 'disabled' }
  });

  return response.choices[0]?.message?.content;
}

高度なユースケース

会話型 Vision Chat

import ZAI from 'z-ai-web-dev-sdk';

class VisionChatSession {
  constructor() {
    this.messages = [];
  }

  async initialize() {
    this.zai = await ZAI.create();
  }

  async addImage(imageUrl, initialQuestion) {
    this.messages.push({
      role: 'user',
      content: [
        {
          type: 'text',
          text: initialQuestion
        },
        {
          type: 'image_url',
          image_url: { url: imageUrl }
        }
      ]
    });

    return this.getResponse();
  }

  async followUp(question) {
    this.messages.push({
      role: 'user',
      content: [
        {
          type: 'text',
          text: question
        }
      ]
    });

    return this.getResponse();
  }

  async getResponse() {
    const response = await this.zai.chat.completions.createVision({
      messages: this.messages,
      thinking: { type: 'disabled' }
    });

    const assistantMessage = response.choices[0]?.message?.content;
    
    this.messages.push({
      role: 'assistant',
      content: assistantMessage
    });

    return assistantMessage;
  }
}

// 使用方法
const session = new VisionChatSession();
await session.initialize();

const initial = await session.addImage(
  'https://example.com/chart.jpg',
  'このチャートは何を表していますか？'
);
console.log('初期分析:', initial);

const followup = await session.followUp('主な傾向は何ですか？');
console.log('フォローアップ:', followup);

画像分類とタギング

import ZAI from 'z-ai-web-dev-sdk';

async function classifyImage(imageUrl) {
  const zai = await ZAI.create();

  const prompt = `この画像を分析し、以下を提供してください:
1. メインのサブジェクト/カテゴリ
2. 検出された主要なオブジェクト
3. シーンの説明
4. 提案されるタグ (カンマ区切り)

JSON 形式で応答をフォーマットしてください。`;

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          {
            type: 'text',
            text: prompt
          },
          {
            type: 'image_url',
            image_url: { url: imageUrl }
          }
        ]
      }
    ],
    thinking: { type: 'disabled' }
  });

  const content = response.choices[0]?.message?.content;
  
  try {
    return JSON.parse(content);
  } catch (e) {
    return { rawResponse: content };
  }
}

OCR とテキスト抽出

import ZAI from 'z-ai-web-dev-sdk';

async function extractText(imageUrl) {
  const zai = await ZAI.create();

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          {
            type: 'text',
            text: 'この画像からすべてのテキストを抽出してください。できるだけレイアウトとフォーマットを保持してください。'
          },
          {
            type: 'image_url',
            image_url: { url: imageUrl }
          }
        ]
      }
    ],
    thinking: { type: 'disabled' }
  });

  return response.choices[0]?.message?.content;
}

ベストプラクティス

1. 画像品質とサイズ

• より良い分析結果のために高品質な画像を使用してください
• 品質と処理速度のバランスを取るために画像サイズを最適化してください
• サポートされているフォーマット: JPEG、PNG、WebP

2. プロンプトエンジニアリング

• 画像から必要な情報について具体的になってください
• 番号付きリストまたは箇条書きで複雑なリクエストを構造化してください
• 画像タイプ (写真、図、グラフなど) についてコンテキストを提供してください

3. エラーハンドリング

async function safeVisionChat(imageUrl, question) {
  try {
    const zai = await ZAI.create();
    
    const response = await zai.chat.completions.createVision({
      messages: [
        {
          role: 'user',
          content: [
            { type: 'text', text: question },
            { type: 'image_url', image_url: { url: imageUrl } }
          ]
        }
      ],
      thinking: { type: 'disabled' }
    });

    return {
      success: true,
      content: response.choices[0]?.message?.content
    };
  } catch (error) {
    console.error('Vision チャートエラー:', error);
    return {
      success: false,
      error: error.message
    };
  }
}

4. パフォーマンス最適化

• 複数の画像を処理する場合は SDK インスタンス作成をキャッシュしてください
• 適切な画像フォーマットを使用してください (写真は JPEG、図は PNG)
• 大規模バッチの場合は画像前処理を検討してください

5. セキュリティに関する考慮事項

• 処理する前に画像 URL を検証してください
• ユーザーが提供した画像データをサニタイズしてください
• パブリック API にはレート制限を実装してください
• SDK 認証情報をクライアント側コードで公開しないでください

一般的なユースケース

1. 製品分析: e-コマース アプリケーション向けに製品画像を分析
2. ドキュメント理解: レシート、請求書、フォームから情報を抽出
3. 医療画像: 適切な免責事項付きで初期分析に支援
4. 品質管理: 製造業での欠陥異常を検出
5. コンテンツモデレーション: ポリシー遵守のために画像を分析
6. アクセシビリティ: 画像の代替テキストを自動生成
7. ビジュアルサーチ: 検索機能のために画像を理解し分類

統合例

Express.js API エンドポイント

import express from 'express';
import ZAI from 'z-ai-web-dev-sdk';

const app = express();
app.use(express.json());

let zaiInstance;

// SDK を一度初期化
async function initZAI() {
  zaiInstance = await ZAI.create();
}

app.post('/api/analyze-image', async (req, res) => {
  try {
    const { imageUrl, question } = req.body;

    if (!imageUrl || !question) {
      return res.status(400).json({ 
        error: 'imageUrl と question は必須です' 
      });
    }

    const response = await zaiInstance.chat.completions.createVision({
      messages: [
        {
          role: 'user',
          content: [
            { type: 'text', text: question },
            { type: 'image_url', image_url: { url: imageUrl } }
          ]
        }
      ],
      thinking: { type: 'disabled' }
    });

    res.json({
      success: true,
      analysis: response.choices[0]?.message?.content
    });
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error.message
    });
  }
});

initZAI().then(() => {
  app.listen(3000, () => {
    console.log('Vision チャート API がポート 3000 で実行中');
  });
});

トラブルシューティング

問題: "SDK はバックエンドのみで使用する必要があります"

• 解決策: z-ai-web-dev-sdk がサーバー側コードでのみインポートおよび使用されていることを確認してください

問題: 画像が読み込まれない、または分析されない

• 解決策: 画像 URL にアクセス可能であり、有効な画像フォーマットを返していることを確認してください

問題: 分析の品質が低い

• 解決策: より具体的なプロンプトを提供し、画像の品質が十分であることを確認してください

問題: レスポンス時間が遅い

• 解決策: 画像サイズを最適化し、頻繁に分析する画像のキャッシュを検討してください

重要なポイント

• 常に z-ai-web-dev-sdk をバックエンドコードでのみ使用してください
• SDK はすでにインストールされています - 例に示すようにインポートしてください
• 最良の結果を得るためにプロンプトを明確に構造化してください
• プロダクション アプリケーションではエラーを適切に処理してください
• 画像を処理する際はユーザーのプライバシーを考慮してください