@nahisaho/katashiro-rag 2.0.0

package/src/embedding/AzureOpenAIEmbeddingProvider.ts

@@ -0,0 +1,208 @@
+/**
+ * Azure OpenAI Embedding Provider
+ *
+ * Azure OpenAI Service embedding provider
+ *
+ * @requirement REQ-RAG-001
+ * @design DES-KATASHIRO-003-RAG
+ */
+
+import { BaseEmbeddingProvider } from './BaseEmbeddingProvider.js';
+import type { EmbeddingConfig } from '../types.js';
+
+/**
+ * Azure OpenAI Embedding設定
+ */
+export interface AzureOpenAIEmbeddingConfig extends EmbeddingConfig {
+  /** Azure OpenAI エンドポイント */
+  endpoint?: string;
+  /** APIキー */
+  apiKey?: string;
+  /** デプロイメント名 */
+  deploymentName?: string;
+  /** APIバージョン */
+  apiVersion?: string;
+}
+
+/**
+ * Azure OpenAI Embedding APIレスポンス
+ */
+interface AzureEmbeddingResponse {
+  object: 'list';
+  data: Array<{
+    object: 'embedding';
+    embedding: number[];
+    index: number;
+  }>;
+  model: string;
+  usage: {
+    prompt_tokens: number;
+    total_tokens: number;
+  };
+}
+
+/**
+ * Azure OpenAI Embeddingプロバイダー
+ *
+ * Azure OpenAI Serviceを使用した埋め込み生成
+ *
+ * @example
+ * ```typescript
+ * const provider = new AzureOpenAIEmbeddingProvider({
+ *   endpoint: 'https://your-resource.openai.azure.com',
+ *   apiKey: process.env.AZURE_OPENAI_API_KEY,
+ *   deploymentName: 'text-embedding-ada-002',
+ *   apiVersion: '2024-02-15-preview',
+ * });
+ *
+ * const embedding = await provider.embed('Hello, world!');
+ * ```
+ */
+export class AzureOpenAIEmbeddingProvider extends BaseEmbeddingProvider {
+  readonly name = 'azure-openai';
+
+  private readonly endpoint: string;
+  private readonly apiKey: string;
+  private readonly deploymentName: string;
+  private readonly apiVersion: string;
+  private _dimensions: number;
+
+  get dimensions(): number {
+    return this._dimensions;
+  }
+
+  constructor(config: AzureOpenAIEmbeddingConfig = {}) {
+    super(config);
+
+    this.endpoint = config.endpoint ?? process.env.AZURE_OPENAI_ENDPOINT ?? '';
+    this.apiKey = config.apiKey ?? process.env.AZURE_OPENAI_API_KEY ?? '';
+    this.deploymentName =
+      config.deploymentName ?? process.env.AZURE_OPENAI_EMBEDDING_DEPLOYMENT ?? '';
+    this.apiVersion = config.apiVersion ?? '2024-02-15-preview';
+
+    // デフォルト次元数
+    this._dimensions = config.dimensions ?? 1536;
+
+    // 設定検証
+    if (!this.endpoint) {
+      throw new Error(
+        'Azure OpenAI endpoint is required. Set AZURE_OPENAI_ENDPOINT or provide endpoint in config.'
+      );
+    }
+    if (!this.apiKey) {
+      throw new Error(
+        'Azure OpenAI API key is required. Set AZURE_OPENAI_API_KEY or provide apiKey in config.'
+      );
+    }
+    if (!this.deploymentName) {
+      throw new Error(
+        'Azure OpenAI deployment name is required. Set AZURE_OPENAI_EMBEDDING_DEPLOYMENT or provide deploymentName in config.'
+      );
+    }
+  }
+
+  /**
+   * 単一テキストの埋め込み生成
+   */
+  async embed(text: string): Promise<number[]> {
+    const embeddings = await this.embedBatchInternal([text]);
+    const result = embeddings[0];
+    if (!result) {
+      throw new Error('Failed to generate embedding');
+    }
+    return result;
+  }
+
+  /**
+   * バッチ埋め込み生成（Azure OpenAI固有実装）
+   */
+  protected override async embedBatchInternal(
+    texts: string[]
+  ): Promise<number[][]> {
+    return this.withRetry(async () => {
+      // エンドポイントの正規化
+      const baseUrl = this.endpoint.endsWith('/')
+        ? this.endpoint.slice(0, -1)
+        : this.endpoint;
+
+      const url = `${baseUrl}/openai/deployments/${this.deploymentName}/embeddings?api-version=${this.apiVersion}`;
+
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+        'api-key': this.apiKey,
+      };
+
+      const body: Record<string, unknown> = {
+        input: texts,
+      };
+
+      // 次元数指定（embedding-3系のみ）
+      if (this._dimensions && this.deploymentName.includes('embedding-3')) {
+        body.dimensions = this._dimensions;
+      }
+
+      const response = await this.fetchWithTimeout(
+        url,
+        {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(body),
+        },
+        this.config.timeout
+      );
+
+      const data = (await response.json()) as AzureEmbeddingResponse;
+
+      // インデックス順にソート
+      const sortedData = [...data.data].sort((a, b) => a.index - b.index);
+
+      // 実際の次元数を更新
+      const firstItem = sortedData[0];
+      if (firstItem) {
+        this._dimensions = firstItem.embedding.length;
+      }
+
+      return sortedData.map((d) => d.embedding);
+    });
+  }
+
+  /**
+   * デプロイメント一覧取得
+   */
+  async listDeployments(): Promise<string[]> {
+    const baseUrl = this.endpoint.endsWith('/')
+      ? this.endpoint.slice(0, -1)
+      : this.endpoint;
+
+    const url = `${baseUrl}/openai/deployments?api-version=${this.apiVersion}`;
+
+    const headers: Record<string, string> = {
+      'api-key': this.apiKey,
+    };
+
+    try {
+      const response = await this.fetchWithTimeout(url, {
+        method: 'GET',
+        headers,
+      });
+
+      interface AzureDeploymentsResponse {
+        data: Array<{
+          id: string;
+          model: string;
+          status: string;
+        }>;
+      }
+
+      const data = (await response.json()) as AzureDeploymentsResponse;
+
+      // embeddingモデルをフィルタ
+      return data.data
+        .filter((d) => d.model.includes('embedding') && d.status === 'succeeded')
+        .map((d) => d.id);
+    } catch {
+      // Azure Management API権限がない場合はエラー
+      return [];
+    }
+  }
+}

package/src/embedding/BaseEmbeddingProvider.ts

@@ -0,0 +1,133 @@
+/**
+ * Base Embedding Provider
+ *
+ * Esperanto-style abstraction for embedding providers
+ *
+ * @requirement REQ-RAG-001
+ * @design DES-KATASHIRO-003-RAG
+ */
+
+import type { EmbeddingProvider, EmbeddingConfig } from '../types.js';
+
+/**
+ * デフォルト設定
+ */
+const DEFAULT_CONFIG: EmbeddingConfig = {
+  batchSize: 100,
+  dimensions: 1536,
+  timeout: 60000,
+  maxRetries: 3,
+};
+
+/**
+ * 抽象Embeddingプロバイダー基底クラス
+ */
+export abstract class BaseEmbeddingProvider implements EmbeddingProvider {
+  abstract readonly name: string;
+  abstract readonly dimensions: number;
+
+  protected config: EmbeddingConfig;
+
+  constructor(config: Partial<EmbeddingConfig> = {}) {
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config,
+    };
+  }
+
+  /**
+   * 単一テキストの埋め込み生成
+   */
+  abstract embed(text: string): Promise<number[]>;
+
+  /**
+   * バッチ埋め込み生成
+   */
+  async embedBatch(texts: string[]): Promise<number[][]> {
+    const batchSize = this.config.batchSize ?? 100;
+    const results: number[][] = [];
+
+    for (let i = 0; i < texts.length; i += batchSize) {
+      const batch = texts.slice(i, i + batchSize);
+      const embeddings = await this.embedBatchInternal(batch);
+      results.push(...embeddings);
+    }
+
+    return results;
+  }
+
+  /**
+   * 内部バッチ処理（プロバイダー固有実装）
+   */
+  protected async embedBatchInternal(texts: string[]): Promise<number[][]> {
+    // デフォルト: 個別に処理
+    return Promise.all(texts.map((text) => this.embed(text)));
+  }
+
+  /**
+   * HTTPリクエストヘルパー（タイムアウト対応）
+   */
+  protected async fetchWithTimeout(
+    url: string,
+    options: RequestInit,
+    timeout?: number
+  ): Promise<Response> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(
+      () => controller.abort(),
+      timeout ?? this.config.timeout
+    );
+
+    try {
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(
+          `HTTP ${response.status}: ${response.statusText} - ${errorText}`
+        );
+      }
+
+      return response;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  /**
+   * リトライ付き実行
+   */
+  protected async withRetry<T>(
+    operation: () => Promise<T>,
+    maxRetries?: number
+  ): Promise<T> {
+    const retries = maxRetries ?? this.config.maxRetries ?? 3;
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        return await operation();
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        if (attempt < retries) {
+          // Exponential backoff
+          const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
+          await this.sleep(delay);
+        }
+      }
+    }
+
+    throw lastError;
+  }
+
+  /**
+   * スリープヘルパー
+   */
+  protected sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/src/embedding/EmbeddingFactory.ts

@@ -0,0 +1,225 @@
+/**
+ * Embedding Provider Factory
+ *
+ * Esperanto-style factory for creating embedding providers
+ *
+ * @requirement REQ-RAG-001
+ * @design DES-KATASHIRO-003-RAG
+ */
+
+import type { EmbeddingProvider, EmbeddingConfig } from '../types.js';
+import { MockEmbeddingProvider } from './MockEmbeddingProvider.js';
+import type { MockEmbeddingProviderConfig } from './MockEmbeddingProvider.js';
+import { OllamaEmbeddingProvider } from './OllamaEmbeddingProvider.js';
+import type { OllamaEmbeddingConfig } from './OllamaEmbeddingProvider.js';
+import { OpenAIEmbeddingProvider } from './OpenAIEmbeddingProvider.js';
+import type { OpenAIEmbeddingConfig } from './OpenAIEmbeddingProvider.js';
+import { AzureOpenAIEmbeddingProvider } from './AzureOpenAIEmbeddingProvider.js';
+import type { AzureOpenAIEmbeddingConfig } from './AzureOpenAIEmbeddingProvider.js';
+
+/**
+ * プロバイダータイプ
+ */
+export type EmbeddingProviderType =
+  | 'mock'
+  | 'ollama'
+  | 'openai'
+  | 'openai-compatible'
+  | 'azure-openai';
+
+/**
+ * プロバイダー設定マップ
+ */
+export interface EmbeddingProviderConfigMap {
+  mock: EmbeddingConfig;
+  ollama: OllamaEmbeddingConfig;
+  openai: OpenAIEmbeddingConfig;
+  'openai-compatible': OpenAIEmbeddingConfig;
+  'azure-openai': AzureOpenAIEmbeddingConfig;
+}
+
+/**
+ * 環境変数から設定を取得
+ */
+function getConfigFromEnv(
+  provider: EmbeddingProviderType
+): Partial<EmbeddingProviderConfigMap[EmbeddingProviderType]> {
+  switch (provider) {
+    case 'ollama':
+      return {
+        baseUrl: process.env.OLLAMA_BASE_URL ?? process.env.OLLAMA_HOST,
+        model: process.env.OLLAMA_EMBEDDING_MODEL,
+      };
+
+    case 'openai':
+      return {
+        apiKey: process.env.OPENAI_API_KEY,
+        organization: process.env.OPENAI_ORGANIZATION,
+        baseUrl: process.env.OPENAI_BASE_URL,
+        model: process.env.OPENAI_EMBEDDING_MODEL,
+      };
+
+    case 'openai-compatible':
+      return {
+        apiKey:
+          process.env.OPENAI_COMPATIBLE_API_KEY_EMBEDDING ??
+          process.env.OPENAI_COMPATIBLE_API_KEY,
+        baseUrl:
+          process.env.OPENAI_COMPATIBLE_BASE_URL_EMBEDDING ??
+          process.env.OPENAI_COMPATIBLE_BASE_URL,
+      };
+
+    case 'azure-openai':
+      return {
+        endpoint: process.env.AZURE_OPENAI_ENDPOINT,
+        apiKey: process.env.AZURE_OPENAI_API_KEY,
+        deploymentName: process.env.AZURE_OPENAI_EMBEDDING_DEPLOYMENT,
+        apiVersion: process.env.AZURE_OPENAI_API_VERSION,
+      };
+
+    default:
+      return {};
+  }
+}
+
+/**
+ * Embedding Provider Factory
+ *
+ * Esperantoスタイルのファクトリクラス
+ *
+ * @example
+ * ```typescript
+ * // 利用可能なプロバイダーを確認
+ * const providers = EmbeddingFactory.getAvailableProviders();
+ *
+ * // プロバイダーを作成
+ * const provider = EmbeddingFactory.create('ollama', {
+ *   baseUrl: 'http://192.168.224.1:11434',
+ *   model: 'nomic-embed-text',
+ * });
+ *
+ * // または環境変数から自動設定
+ * const provider = EmbeddingFactory.create('openai');
+ * ```
+ */
+export class EmbeddingFactory {
+  /**
+   * プロバイダー作成
+   */
+  static create<T extends EmbeddingProviderType>(
+    provider: T,
+    config?: Partial<EmbeddingProviderConfigMap[T]>
+  ): EmbeddingProvider {
+    // 環境変数からの設定とマージ
+    const envConfig = getConfigFromEnv(provider);
+    const mergedConfig = { ...envConfig, ...config };
+
+    switch (provider) {
+      case 'mock':
+        return new MockEmbeddingProvider({
+          dimensions: (mergedConfig as MockEmbeddingProviderConfig).dimensions ?? 1536,
+          delay: (mergedConfig as MockEmbeddingProviderConfig).delay ?? 0,
+          shouldFail: (mergedConfig as MockEmbeddingProviderConfig).shouldFail ?? false,
+        });
+
+      case 'ollama':
+        return new OllamaEmbeddingProvider(
+          mergedConfig as OllamaEmbeddingConfig
+        );
+
+      case 'openai':
+      case 'openai-compatible':
+        return new OpenAIEmbeddingProvider(
+          mergedConfig as OpenAIEmbeddingConfig
+        );
+
+      case 'azure-openai':
+        return new AzureOpenAIEmbeddingProvider(
+          mergedConfig as AzureOpenAIEmbeddingConfig
+        );
+
+      default:
+        throw new Error(`Unknown embedding provider: ${provider}`);
+    }
+  }
+
+  /**
+   * 利用可能なプロバイダー一覧
+   */
+  static getAvailableProviders(): EmbeddingProviderType[] {
+    return ['mock', 'ollama', 'openai', 'openai-compatible', 'azure-openai'];
+  }
+
+  /**
+   * デフォルトプロバイダー取得
+   *
+   * 環境変数から自動判定
+   */
+  static getDefaultProvider(): EmbeddingProvider {
+    // 優先順位: AZURE > OPENAI > OLLAMA > MOCK
+    if (
+      process.env.AZURE_OPENAI_ENDPOINT &&
+      process.env.AZURE_OPENAI_API_KEY
+    ) {
+      return this.create('azure-openai');
+    }
+
+    if (process.env.OPENAI_API_KEY) {
+      return this.create('openai');
+    }
+
+    if (process.env.OLLAMA_BASE_URL || process.env.OLLAMA_HOST) {
+      return this.create('ollama');
+    }
+
+    // フォールバック: モック
+    return this.create('mock');
+  }
+
+  /**
+   * プロバイダーの利用可能確認
+   */
+  static isProviderConfigured(provider: EmbeddingProviderType): boolean {
+    switch (provider) {
+      case 'mock':
+        return true;
+
+      case 'ollama':
+        return !!(process.env.OLLAMA_BASE_URL || process.env.OLLAMA_HOST);
+
+      case 'openai':
+        return !!process.env.OPENAI_API_KEY;
+
+      case 'openai-compatible':
+        return !!(
+          process.env.OPENAI_COMPATIBLE_BASE_URL_EMBEDDING ||
+          process.env.OPENAI_COMPATIBLE_BASE_URL
+        );
+
+      case 'azure-openai':
+        return !!(
+          process.env.AZURE_OPENAI_ENDPOINT && process.env.AZURE_OPENAI_API_KEY
+        );
+
+      default:
+        return false;
+    }
+  }
+}
+
+/**
+ * 便利関数: Embeddingプロバイダー作成
+ */
+export function createEmbeddingProvider<T extends EmbeddingProviderType>(
+  provider: T,
+  config?: Partial<EmbeddingProviderConfigMap[T]>
+): EmbeddingProvider {
+  return EmbeddingFactory.create(provider, config);
+}
+
+/**
+ * 便利関数: デフォルトプロバイダー取得
+ */
+export function getDefaultEmbeddingProvider(): EmbeddingProvider {
+  return EmbeddingFactory.getDefaultProvider();
+}

package/src/embedding/EmbeddingManager.ts

@@ -0,0 +1,110 @@
+/**
+ * Embedding Manager
+ *
+ * @requirement REQ-RAG-001
+ * @design DES-KATASHIRO-003-RAG §3.1
+ */
+
+import type { EmbeddingProvider, Vector } from '../types.js';
+
+/**
+ * EmbeddingManager - Embedding生成の管理
+ * キャッシュとバッチ処理をサポート
+ */
+export class EmbeddingManager {
+  private provider: EmbeddingProvider;
+  private cache: Map<string, Vector> = new Map();
+
+  constructor(provider: EmbeddingProvider) {
+    this.provider = provider;
+  }
+
+  /**
+   * ベクトル次元数
+   */
+  get dimensions(): number {
+    return this.provider.dimensions;
+  }
+
+  /**
+   * プロバイダー名
+   */
+  get providerName(): string {
+    return this.provider.name;
+  }
+
+  /**
+   * 単一テキストの埋め込み生成
+   */
+  async embed(text: string): Promise<Vector> {
+    // キャッシュチェック
+    const cacheKey = this.getCacheKey(text);
+    const cached = this.cache.get(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    // 生成
+    const embedding = await this.provider.embed(text);
+
+    // キャッシュ保存
+    this.cache.set(cacheKey, embedding);
+
+    return embedding;
+  }
+
+  /**
+   * バッチ埋め込み生成
+   */
+  async embedBatch(texts: string[]): Promise<Vector[]> {
+    // 全部キャッシュチェックして、なければ一括生成
+    const results: Vector[] = new Array(texts.length);
+    const uncachedTexts: string[] = [];
+    const uncachedIndices: number[] = [];
+
+    for (let i = 0; i < texts.length; i++) {
+      const text = texts[i]!;
+      const cacheKey = this.getCacheKey(text);
+      const cached = this.cache.get(cacheKey);
+      if (cached) {
+        results[i] = cached;
+      } else {
+        uncachedTexts.push(text);
+        uncachedIndices.push(i);
+      }
+    }
+
+    // 未キャッシュのものを生成
+    if (uncachedTexts.length > 0) {
+      const newEmbeddings = await this.provider.embedBatch(uncachedTexts);
+
+      for (let j = 0; j < newEmbeddings.length; j++) {
+        const originalIndex = uncachedIndices[j]!;
+        const text = uncachedTexts[j]!;
+        const embedding = newEmbeddings[j]!;
+
+        results[originalIndex] = embedding;
+
+        // キャッシュ保存
+        const cacheKey = this.getCacheKey(text);
+        this.cache.set(cacheKey, embedding);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * キャッシュをクリア
+   */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * キャッシュキーを生成
+   */
+  private getCacheKey(text: string): string {
+    return `${this.provider.name}:${text}`;
+  }
+}