Perplexity信頼性パターン

概要

Perplexity統合向けのプロダクショングレードの信頼性パターンです。

前提条件

• サーキットブレーカーパターンの理解
• opossumまたは同様のライブラリのインストール
• DLQ用のキュー基盤
• フォールバック用のキャッシング層

サーキットブレーカー

import CircuitBreaker from 'opossum';

const perplexityBreaker = new CircuitBreaker(
  async (operation: () => Promise<any>) => operation(),
  {
    timeout: 30000,
    errorThresholdPercentage: 50,
    resetTimeout: 30000,
    volumeThreshold: 10,
  }
);

// イベント
perplexityBreaker.on('open', () => {
  console.warn('Perplexity circuit OPEN - requests failing fast');
  alertOps('Perplexity circuit breaker opened');
});

perplexityBreaker.on('halfOpen', () => {
  console.info('Perplexity circuit HALF-OPEN - testing recovery');
});

perplexityBreaker.on('close', () => {
  console.info('Perplexity circuit CLOSED - normal operation');
});

// 使用方法
async function safePerplexityCall<T>(fn: () => Promise<T>): Promise<T> {
  return perplexityBreaker.fire(fn);
}

べき等性キー

import { v4 as uuidv4 } from 'uuid';
import crypto from 'crypto';

// 入力から決定的なべき等性キーを生成
function generateIdempotencyKey(
  operation: string,
  params: Record<string, any>
): string {
  const data = JSON.stringify({ operation, params });
  return crypto.createHash('sha256').update(data).digest('hex');
}

// またはストレージを使用したランダムキー
class IdempotencyManager {
  private store: Map<string, { key: string; expiresAt: Date }> = new Map();

  getOrCreate(operationId: string): string {
    const existing = this.store.get(operationId);
    if (existing && existing.expiresAt > new Date()) {
      return existing.key;
    }

    const key = uuidv4();
    this.store.set(operationId, {
      key,
      expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
    });
    return key;
  }
}

バルクヘッドパターン

import PQueue from 'p-queue';

// 異なる操作向けの個別キュー
const perplexityQueues = {
  critical: new PQueue({ concurrency: 10 }),
  normal: new PQueue({ concurrency: 5 }),
  bulk: new PQueue({ concurrency: 2 }),
};

async function prioritizedPerplexityCall<T>(
  priority: 'critical' | 'normal' | 'bulk',
  fn: () => Promise<T>
): Promise<T> {
  return perplexityQueues[priority].add(fn);
}

// 使用方法
await prioritizedPerplexityCall('critical', () =>
  perplexityClient.processPayment(order)
);

await prioritizedPerplexityCall('bulk', () =>
  perplexityClient.syncCatalog(products)
);

タイムアウト階層

const TIMEOUT_CONFIG = {
  connect: 5000,      // 初期接続
  request: 30000,     // 標準リクエスト
  upload: 120000,     // ファイルアップロード
  longPoll: 300000,   // Webhookロングポーリング
};

async function timedoutPerplexityCall<T>(
  operation: 'connect' | 'request' | 'upload' | 'longPoll',
  fn: () => Promise<T>
): Promise<T> {
  const timeout = TIMEOUT_CONFIG[operation];

  return Promise.race([
    fn(),
    new Promise<never>((_, reject) =>
      setTimeout(() => reject(new Error(`Perplexity ${operation} timeout`)), timeout)
    ),
  ]);
}

グレースフルデグラデーション

interface PerplexityFallback {
  enabled: boolean;
  data: any;
  staleness: 'fresh' | 'stale' | 'very_stale';
}

async function withPerplexityFallback<T>(
  fn: () => Promise<T>,
  fallbackFn: () => Promise<T>
): Promise<{ data: T; fallback: boolean }> {
  try {
    const data = await fn();
    // 今後のフォールバック用にキャッシュを更新
    await updateFallbackCache(data);
    return { data, fallback: false };
  } catch (error) {
    console.warn('Perplexity failed, using fallback:', error.message);
    const data = await fallbackFn();
    return { data, fallback: true };
  }
}

デッドレターキュー

interface DeadLetterEntry {
  id: string;
  operation: string;
  payload: any;
  error: string;
  attempts: number;
  lastAttempt: Date;
}

class PerplexityDeadLetterQueue {
  private queue: DeadLetterEntry[] = [];

  add(entry: Omit<DeadLetterEntry, 'id' | 'lastAttempt'>): void {
    this.queue.push({
      ...entry,
      id: uuidv4(),
      lastAttempt: new Date(),
    });
  }

  async processOne(): Promise<boolean> {
    const entry = this.queue.shift();
    if (!entry) return false;

    try {
      await perplexityClient[entry.operation](entry.payload);
      console.log(`DLQ: Successfully reprocessed ${entry.id}`);
      return true;
    } catch (error) {
      entry.attempts++;
      entry.lastAttempt = new Date();

      if (entry.attempts < 5) {
        this.queue.push(entry);
      } else {
        console.error(`DLQ: Giving up on ${entry.id} after 5 attempts`);
        await alertOnPermanentFailure(entry);
      }
      return false;
    }
  }
}

デグラデーション状態でのヘルスチェック

type HealthStatus = 'healthy' | 'degraded' | 'unhealthy';

async function perplexityHealthCheck(): Promise<{
  status: HealthStatus;
  details: Record<string, any>;
}> {
  const checks = {
    api: await checkApiConnectivity(),
    circuitBreaker: perplexityBreaker.stats(),
    dlqSize: deadLetterQueue.size(),
  };

  const status: HealthStatus =
    !checks.api.connected ? 'unhealthy' :
    checks.circuitBreaker.state === 'open' ? 'degraded' :
    checks.dlqSize > 100 ? 'degraded' :
    'healthy';

  return { status, details: checks };
}

手順

ステップ1: サーキットブレーカーの実装

Perplexityの呼び出しをサーキットブレーカーでラップします。

ステップ2: べき等性キーの追加

操作向けに決定的なキーを生成します。

ステップ3: バルクヘッドの設定

優先度の異なるキューを分離します。

ステップ4: デッドレターキューの設定

永続的な障害を適切に処理します。

出力

• Perplexity呼び出しを保護するサーキットブレーカー
• 重複を防ぐべき等性
• 実装されたバルクヘッド分離
• 失敗した操作用のDLQ

エラーハンドリング

問題	原因	解決策
サーキットがオープン状態のままになる	閾値が低すぎる	エラー率を調整
重複した操作	べき等性が不足	べき等性キーを追加
キューがいっぱい	レートが高すぎる	並行性を増加
DLQが増加	永続的な障害	ルート原因を調査

例

クイックサーキットチェック

const state = perplexityBreaker.stats().state;
console.log('Perplexity circuit:', state);

リソース

• Circuit Breaker Pattern
• Opossum Documentation
• Perplexity Reliability Guide

次のステップ

ポリシー実行については、perplexity-policy-guardrailsを参照してください。