@reftrixmcp/ml 0.1.7

package/dist/embeddings/multimodal-embedding.service.d.ts

@@ -0,0 +1,400 @@
+/**
+ * Multimodal Embedding Service
+ *
+ * VisionAnalyzerの特徴抽出結果とテキストEmbeddingを組み合わせて
+ * マルチモーダルEmbeddingを生成します。
+ *
+ * text_embedding + vision_embedding の統合サービス
+ * - searchMode: 'text_only' | 'vision_only' | 'combined'
+ * - Graceful Degradation: visionFeaturesがない場合はtext_onlyにフォールバック
+ * - L2正規化: すべてのEmbeddingは正規化される
+ *
+ * @module embeddings/multimodal-embedding.service
+ */
+import { z } from "zod";
+import type { VisionFeatures } from "./vision-embedding.types.js";
+/**
+ * 検索モード
+ */
+export type SearchMode = "text_only" | "vision_only" | "combined";
+/**
+ * マルチモーダルEmbedding設定
+ */
+export interface MultimodalEmbeddingConfig {
+    /** テキストEmbeddingの重み (0-1) */
+    textWeight?: number;
+    /** Vision Embeddingの重み (0-1) */
+    visionWeight?: number;
+    /** Embeddingの次元数 */
+    embeddingDimension?: number;
+    /** 検索モード */
+    searchMode?: SearchMode;
+    /** 出力のL2正規化 */
+    normalizeOutput?: boolean;
+}
+/**
+ * デフォルト設定
+ */
+export declare const DEFAULT_MULTIMODAL_CONFIG: Required<MultimodalEmbeddingConfig>;
+/**
+ * 設定スキーマ
+ */
+export declare const multimodalEmbeddingConfigSchema: z.ZodObject<{
+    textWeight: z.ZodOptional<z.ZodNumber>;
+    visionWeight: z.ZodOptional<z.ZodNumber>;
+    embeddingDimension: z.ZodOptional<z.ZodNumber>;
+    searchMode: z.ZodOptional<z.ZodEnum<["text_only", "vision_only", "combined"]>>;
+    normalizeOutput: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    textWeight?: number | undefined;
+    visionWeight?: number | undefined;
+    embeddingDimension?: number | undefined;
+    searchMode?: "text_only" | "vision_only" | "combined" | undefined;
+    normalizeOutput?: boolean | undefined;
+}, {
+    textWeight?: number | undefined;
+    visionWeight?: number | undefined;
+    embeddingDimension?: number | undefined;
+    searchMode?: "text_only" | "vision_only" | "combined" | undefined;
+    normalizeOutput?: boolean | undefined;
+}>;
+/**
+ * マルチモーダルEmbedding入力
+ */
+export interface MultimodalEmbeddingInput {
+    /** テキスト表現（VisionAnalyzer.generateTextRepresentationの出力） */
+    textRepresentation: string;
+    /** Vision特徴からのテキスト（カラーパレット、レイアウト等） */
+    visionFeatureText?: string;
+    /** 元のテキスト（名前、説明等） */
+    originalText?: string;
+}
+/**
+ * 入力スキーマ
+ */
+export declare const multimodalEmbeddingInputSchema: z.ZodObject<{
+    textRepresentation: z.ZodString;
+    visionFeatureText: z.ZodOptional<z.ZodString>;
+    originalText: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    textRepresentation: string;
+    visionFeatureText?: string | undefined;
+    originalText?: string | undefined;
+}, {
+    textRepresentation: string;
+    visionFeatureText?: string | undefined;
+    originalText?: string | undefined;
+}>;
+/**
+ * マルチモーダルEmbedding結果
+ */
+export interface MultimodalEmbeddingResult {
+    /** 統合Embedding (768次元) */
+    combinedEmbedding: number[];
+    /** テキストEmbedding (768次元) */
+    textEmbedding: number[];
+    /** Vision特徴Embedding (768次元) */
+    visionEmbedding: number[];
+    /** 使用した重み */
+    weights: {
+        text: number;
+        vision: number;
+    };
+    /** 処理時間（ミリ秒） */
+    processingTimeMs: number;
+}
+/**
+ * 結果スキーマ
+ */
+export declare const multimodalEmbeddingResultSchema: z.ZodObject<{
+    combinedEmbedding: z.ZodArray<z.ZodNumber, "many">;
+    textEmbedding: z.ZodArray<z.ZodNumber, "many">;
+    visionEmbedding: z.ZodArray<z.ZodNumber, "many">;
+    weights: z.ZodObject<{
+        text: z.ZodNumber;
+        vision: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        text: number;
+        vision: number;
+    }, {
+        text: number;
+        vision: number;
+    }>;
+    processingTimeMs: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    combinedEmbedding: number[];
+    textEmbedding: number[];
+    visionEmbedding: number[];
+    weights: {
+        text: number;
+        vision: number;
+    };
+    processingTimeMs: number;
+}, {
+    combinedEmbedding: number[];
+    textEmbedding: number[];
+    visionEmbedding: number[];
+    weights: {
+        text: number;
+        vision: number;
+    };
+    processingTimeMs: number;
+}>;
+/**
+ * 新しいマルチモーダルEmbedding結果
+ */
+export interface MultimodalEmbeddingResultV2 {
+    /** テキストEmbedding (768次元、L2正規化済み) */
+    textEmbedding: number[] | null;
+    /** Vision Embedding (768次元、L2正規化済み) */
+    visionEmbedding: number[] | null;
+    /** 統合Embedding (768次元、L2正規化済み) */
+    combinedEmbedding: number[] | null;
+    /** 使用した検索モード */
+    searchMode: SearchMode;
+    /** 使用した重み */
+    weights: {
+        text: number;
+        vision: number;
+    };
+    /** メタデータ */
+    metadata: {
+        /** テキスト表現 */
+        textRepresentation: string;
+        /** VisionFeatures (combinedモード時のみ) */
+        visionFeatures?: VisionFeatures;
+        /** 処理時間（ミリ秒） */
+        processingTimeMs: number;
+    };
+}
+/**
+ * バッチ処理入力アイテム
+ */
+export interface MultimodalBatchItem {
+    /** テキストコンテンツ */
+    content: string;
+    /** VisionFeatures（オプション） */
+    visionFeatures?: VisionFeatures;
+}
+/**
+ * バッチ処理結果
+ */
+export interface MultimodalBatchResult {
+    /** 成功した結果 */
+    results: MultimodalEmbeddingResultV2[];
+    /** 処理統計 */
+    stats: {
+        /** 処理件数 */
+        total: number;
+        /** 成功件数 */
+        success: number;
+        /** 失敗件数 */
+        failed: number;
+        /** 合計処理時間（ミリ秒） */
+        totalProcessingTimeMs: number;
+    };
+}
+/**
+ * バッチ処理パフォーマンスメトリクス
+ */
+export interface MultimodalBatchMetrics {
+    /** 総アイテム数 */
+    totalItems: number;
+    /** 成功件数 */
+    successCount: number;
+    /** 失敗件数 */
+    failedCount: number;
+    /** キャッシュヒット件数 */
+    cacheHitCount: number;
+    /** キャッシュヒット率 (0-1) */
+    cacheHitRate: number;
+    /** 平均処理時間（ミリ秒） */
+    avgProcessingTimeMs: number;
+    /** 合計処理時間（ミリ秒） */
+    totalProcessingTimeMs: number;
+    /** スループット（件/分） */
+    throughputPerMinute: number;
+}
+/**
+ * 最適化バッチ処理の進捗情報
+ */
+export interface OptimizedBatchProgress {
+    /** 完了件数 */
+    completed: number;
+    /** 総件数 */
+    total: number;
+    /** 進捗率 (0-1) */
+    progress: number;
+    /** 現在のアイテムインデックス */
+    currentIndex: number;
+}
+/**
+ * 最適化バッチ処理オプション
+ */
+export interface OptimizedBatchOptions {
+    /** 並列処理の同時実行数 (デフォルト: 5) */
+    concurrency?: number;
+    /** 個別アイテムのタイムアウト（ミリ秒）(デフォルト: 30000) */
+    itemTimeoutMs?: number;
+    /** バッチ全体のタイムアウト（ミリ秒）(デフォルト: 300000 = 5分) */
+    totalTimeoutMs?: number;
+    /** 進捗コールバック */
+    onProgress?: (progress: OptimizedBatchProgress) => void;
+    /** Embedding設定のオーバーライド */
+    embeddingConfig?: MultimodalEmbeddingConfig;
+}
+/**
+ * 最適化バッチ処理結果
+ */
+export interface OptimizedBatchResult {
+    /** 成功した結果 */
+    results: MultimodalEmbeddingResultV2[];
+    /** パフォーマンスメトリクス */
+    metrics: MultimodalBatchMetrics;
+    /** エラー情報（失敗したアイテム） */
+    errors: Array<{
+        index: number;
+        error: string;
+    }>;
+}
+/**
+ * Embeddingサービスインターフェース（DI用）
+ */
+export interface IEmbeddingService {
+    generateEmbedding(text: string, type: "query" | "passage"): Promise<number[]>;
+}
+/**
+ * マルチモーダルEmbeddingサービス
+ *
+ * VisionAnalyzerの特徴抽出結果とテキストEmbeddingを組み合わせて
+ * 統合Embeddingを生成します。
+ *
+ * @example
+ * ```typescript
+ * const service = new MultimodalEmbeddingService(embeddingService);
+ *
+ * const result = await service.generateMultimodalEmbedding({
+ *   textRepresentation: "Layout: two-column grid...",
+ *   visionFeatureText: "Colors: blue, white. Whitespace: generous.",
+ *   originalText: "Hero section design",
+ * });
+ *
+ * console.log(result.combinedEmbedding.length); // 768
+ * ```
+ */
+export declare class MultimodalEmbeddingService {
+    private config;
+    private embeddingService;
+    constructor(embeddingService: IEmbeddingService, config?: MultimodalEmbeddingConfig);
+    /**
+     * 重みを正規化（合計が1になるように）
+     */
+    private normalizeWeights;
+    /**
+     * マルチモーダルEmbeddingを生成
+     *
+     * @param input - 入力データ
+     * @returns マルチモーダルEmbedding結果
+     */
+    generateMultimodalEmbedding(input: MultimodalEmbeddingInput): Promise<MultimodalEmbeddingResult>;
+    /**
+     * テキストEmbedding用の文字列を構築
+     */
+    private buildTextForEmbedding;
+    /**
+     * Vision特徴テキストを構築
+     */
+    private buildVisionText;
+    /**
+     * 2つのEmbeddingを重み付き結合
+     */
+    private combineEmbeddings;
+    /**
+     * ベクトルをL2正規化
+     */
+    private normalizeVector;
+    /**
+     * 現在の設定を取得
+     */
+    getConfig(): Readonly<Required<MultimodalEmbeddingConfig>>;
+    /**
+     * マルチモーダルEmbeddingを生成
+     *
+     * searchModeに応じて適切なEmbeddingを生成します。
+     * - text_only: テキストEmbeddingのみ
+     * - vision_only: VisionEmbeddingのみ（visionFeatures必須）
+     * - combined: テキスト + Vision の重み付き結合
+     *
+     * Graceful Degradation:
+     * - visionFeaturesがない場合、combinedモードはtext_onlyにフォールバック
+     *
+     * @param content - テキストコンテンツ
+     * @param visionFeatures - VisionFeatures（オプション）
+     * @param config - オーバーライド設定（オプション）
+     * @returns MultimodalEmbeddingResultV2
+     */
+    createMultimodalEmbedding(content: string, visionFeatures?: VisionFeatures, config?: MultimodalEmbeddingConfig): Promise<MultimodalEmbeddingResultV2>;
+    /**
+     * バッチでマルチモーダルEmbeddingを生成
+     *
+     * @param items - バッチ処理入力アイテムの配列
+     * @param config - オーバーライド設定（オプション）
+     * @returns MultimodalBatchResult
+     */
+    createBatchMultimodalEmbeddings(items: MultimodalBatchItem[], config?: MultimodalEmbeddingConfig): Promise<MultimodalBatchResult>;
+    /**
+     * 設定をマージ
+     */
+    private mergeConfig;
+    /**
+     * 設定を使用して2つのEmbeddingを重み付き結合
+     */
+    private combineEmbeddingsWithConfig;
+    /** キャッシュ（コンテンツハッシュ -> 結果） */
+    private embeddingCache;
+    /** 最大キャッシュサイズ */
+    private readonly maxCacheSize;
+    /**
+     * キャッシュキーを生成
+     */
+    private generateCacheKey;
+    /**
+     * キャッシュから取得（LRU更新）
+     */
+    private getCacheEntry;
+    /**
+     * キャッシュに保存（LRU eviction）
+     */
+    private setCacheEntry;
+    /**
+     * 最適化バッチでマルチモーダルEmbeddingを生成
+     *
+     * p-limitを使用した並列処理により、高スループットを実現します。
+     *
+     * 特徴:
+     * - 並列処理（デフォルト同時実行数: 5）
+     * - キャッシュによる重複処理の回避
+     * - 個別アイテムタイムアウト
+     * - バッチ全体タイムアウト
+     * - 進捗コールバック
+     * - Graceful Degradation（部分失敗許容）
+     * - 詳細なパフォーマンスメトリクス
+     *
+     * @param items - バッチ処理入力アイテムの配列
+     * @param options - 最適化オプション
+     * @returns OptimizedBatchResult
+     */
+    createOptimizedBatchMultimodalEmbeddings(items: MultimodalBatchItem[], options?: OptimizedBatchOptions): Promise<OptimizedBatchResult>;
+    /**
+     * Embeddingキャッシュをクリア
+     */
+    clearEmbeddingCache(): void;
+    /**
+     * キャッシュ統計を取得
+     */
+    getEmbeddingCacheStats(): {
+        size: number;
+        maxSize: number;
+    };
+}
+//# sourceMappingURL=multimodal-embedding.service.d.ts.map

package/dist/embeddings/multimodal-embedding.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multimodal-embedding.service.d.ts","sourceRoot":"","sources":["../../src/embeddings/multimodal-embedding.service.ts"],"names":[],"mappings":"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"}