AIチャット機能ドキュメント

概要

AIチャット機能は、OpenAIのAPIを使用して製品レビューと比較に基づいたレスポンスを生成するリアルタイムチャット機能を提供します。このシステムは標準レスポンスとストリーミングレスポンスの両方をサポートしています。

システムアーキテクチャ

1. ストリームチャットフロー

sequenceDiagram
    actor Client
    participant APIServer
    participant DatasetDao
    participant SimilarProductChatSettingDao
    participant ProductSimilarService
    participant GPTService
    participant SimilarProductChatHistoryDao

    Client->>APIServer: POST /api/similar_products/stream_chat
    activate APIServer
    
    APIServer->>APIServer: リクエストデータの検証
    
    APIServer->>DatasetDao: dataset_idによるデータセット取得
    alt データセットが見つからない場合
        DatasetDao-->>APIServer: 404 Not Found
        APIServer-->>Client: 404 エラーレスポンス
    end
    DatasetDao-->>APIServer: データセット
    
    APIServer->>SimilarProductChatSettingDao: thread_idによる設定取得
    alt 設定が見つからない場合
        SimilarProductChatSettingDao-->>APIServer: 空の設定
        Note over APIServer: デフォルト値を使用:<br/>model: gpt-4o<br/>temperature: 0.7
    end
    SimilarProductChatSettingDao-->>APIServer: チャット設定
    
    APIServer->>ProductSimilarService: prepare_chat()
    ProductSimilarService->>ProductSimilarService: set_system_prompt_variable()
    ProductSimilarService->>SimilarProductChatHistoryDao: システムメッセージを保存
    ProductSimilarService->>SimilarProductChatHistoryDao: ユーザーメッセージを保存
    ProductSimilarService-->>APIServer: 準備されたメッセージ
    
    APIServer->>GPTService: stream_message()
    activate GPTService
    loop 各チャンクに対して
        GPTService-->>APIServer: ストリームチャンク
        APIServer-->>Client: チャンク送信
    end
    deactivate GPTService
    
    APIServer->>SimilarProductChatHistoryDao: 完全なレスポンスを保存
    deactivate APIServer

2. 標準チャットフロー

sequenceDiagram
    actor Client
    participant APIServer
    participant DatasetDao
    participant SimilarProductChatSettingDao
    participant ProductSimilarService
    participant GPTService
    participant SimilarProductChatHistoryDao

    Client->>APIServer: POST /api/similar_products/standard-chat
    activate APIServer
    
    APIServer->>APIServer: リクエストデータの検証
    
    APIServer->>DatasetDao: dataset_idによるデータセット取得
    alt データセットが見つからない場合
        DatasetDao-->>APIServer: 404 Not Found
        APIServer-->>Client: 404 エラーレスポンス
    end
    DatasetDao-->>APIServer: データセット
    
    APIServer->>SimilarProductChatSettingDao: thread_idによる設定取得
    alt 設定が見つからない場合
        SimilarProductChatSettingDao-->>APIServer: 空の設定
        Note over APIServer: デフォルト値を使用:<br/>model: gpt-4o<br/>temperature: 0.7
    end
    SimilarProductChatSettingDao-->>APIServer: チャット設定
    
    APIServer->>ProductSimilarService: prepare_chat()
    ProductSimilarService->>ProductSimilarService: set_system_prompt_variable()
    ProductSimilarService->>SimilarProductChatHistoryDao: システムメッセージを保存
    ProductSimilarService->>SimilarProductChatHistoryDao: ユーザーメッセージを保存
    ProductSimilarService-->>APIServer: 準備されたメッセージ
    
    APIServer->>GPTService: standard_message()
    GPTService-->>APIServer: 完全なレスポンス
    
    APIServer->>SimilarProductChatHistoryDao: レスポンスを保存
    APIServer-->>Client: レスポンス返却
    deactivate APIServer

3. データ処理フロー

flowchart TD
    A[開始] --> B[チャット設定取得]
    B --> C[チャット履歴読み込み]
    C --> D[製品情報取得]
    D --> E[レビューデータ取得]
    
    E --> F{共通の観点がある?}
    F -->|はい| G[サブ観点付きレビュー取得]
    F -->|いいえ| H[通常レビュー取得]
    
    G --> I[レビュー処理]
    H --> I
    
    I --> J[フィルター適用]
    J --> K[ランダムサンプリング]
    K --> L[レスポンスフォーマット]
    
    subgraph "レビュー処理"
    J --> |フィルターオプション|M[製品ID]
    J --> |フィルターオプション|N[観点ID]
    J --> |フィルターオプション|O[感情スコア]
    J --> |フィルターオプション|P[日付範囲]
    end
    
    K --> |製品ごとに最大30件|Q[レビュー制限]

4. エラー処理フロー

flowchart TD
    A[リクエスト] --> B{リクエスト検証}
    B -->|無効| C[400を返却]
    B -->|有効| D{データセット確認}
    
    D -->|見つからない| E[404を返却]
    D -->|見つかった| F{リクエスト処理}
    
    F -->|ストリームエラー| G[エラーログ記録]
    G --> H[部分レスポンスを保存]
    H --> I[エラーステータス返却]
    
    F -->|成功| J[レスポンス返却]
    
    subgraph "ストリームエラー処理"
    K[ストリーム中断] --> L[CancelledError]
    L --> M[警告ログ記録]
    M --> N[現在のコンテンツを保存]
    
    O[その他のエラー] --> P[エラーログ記録]
    P --> Q[エラー状態を保存]
    end

主要コンポーネントの相互作用

リクエスト処理レイヤー
- 受信リクエストを検証
- リクエストルーティングを処理
- レスポンス形式を管理
サービスレイヤー
- ProductSimilarService: コアビジネスロジック
- GPTService: OpenAI API連携
- データ準備と変換を処理
データアクセスレイヤー
- DAOを通じたデータベース操作
- データ検証と変換
- キャッシュ管理
外部連携
- OpenAI APIとの通信
- ストリーミングレスポンス処理
- エラー回復メカニズム

パフォーマンスに関する考慮事項

ストリーミング最適化
- チャンクがすぐに処理され送信される
- 大きなレスポンスに対してメモリ効率が良い
- 接続中断を処理する
データベース操作
- 効率的なクエリパターン
- 頻繁なクエリに対する適切なインデックス
- データ一貫性のためのトランザクション管理
エラー回復
- APIの障害を適切に処理
- 部分的なレスポンス保存
- 自動再試行メカニズム

コアコンポーネント

1. サービスレイヤー

GPTService (base/service/gpt_service.py)
- OpenAI API連携を処理
- 標準およびストリーミングレスポンスをサポート
- メソッド:
  - standard_message(): 通常のチャット完了
  - stream_message(): ストリーミングチャット完了
ProductSimilarService (base/service/product_similar_service.py)
- チャット機能のコアビジネスロジック
- メソッド:
  - prepare_chat(): チャットメッセージと設定を準備
  - stream_chat(): ストリーミングレスポンスを処理
  - standard_chat(): 標準レスポンスを処理
  - set_system_prompt_variable(): コンテキスト付きのシステムプロンプトを設定

2. データアクセスレイヤー

SimilarProductChatSettingDao: チャット設定を管理
SimilarProductChatHistoryDao: チャット履歴を処理
DatasetDao: データセットを管理
AnalyzedSimilarProductReviewSentenceDao: レビューデータを管理

詳細プロセスフロー

チャットリクエスト処理

リクエスト検証

flowchart TD
    A[クライアントリクエスト] --> B[リクエストデータ検証]
    B --> C{有効?}
    C -->|はい| D[リクエスト処理]
    C -->|いいえ| E[400エラー返却]

チャット準備

チャット設定の取得（存在しない場合はデフォルト）:
- モデル: gpt-4o
- 温度: 0.7
- システムプロンプト: SIMILAR_PRODUCT_CHAT_PROMPT

{
  "role": "system",
  "content": "あなたは、ECサイトの商品情報を分析し、自社商品と競合商品の性能や人気度、価格設定、顧客評価などを比較することです。
  これにより、ユーザーが競争力のある商品戦略を立案できるようサポートします。

  以下に分析に必要なデータを入力します。このデータを元にユーザーからの質問に回答してください。

  * 類似商品情報
  類似商品情報はベース商品に対して、競合商品が商品情報・画像・レビューの評価観点がどれだけ類似しているかを示す情報です。
  ** データの内容
  *** ベース商品情報
  {base_product_info}
  *** 類似情報
  {similar_table}"
}

チャット履歴の読み込み
システムプロンプト付きのメッセージ配列の準備

レビューデータ処理
- 以下に基づいてレビューをフィルタリング:
  - 製品ID
  - 観点ID
  - 感情スコア
  - 日付範囲
  - 共通観点ID
  - サブ観点ID

レスポンス処理

ストリーミングレスポンス

OpenAI APIからのチャンクを処理
各チャンクをクライアントに送信
完全なレスポンスをチャット履歴に保存

ストリーム中断の処理:

try:
    for chunk in stream:
        if chunk.choices[0].delta.content is not None:
            content = chunk.choices[0].delta.content
            res_content.append(content)
            yield content
except asyncio.CancelledError:
    logging.warn("ストリーム中断")
    # 部分レスポンスを履歴に保存
except Exception as e:
    logging.error(f"エラー: {e}")
finally:
    # 完全なレスポンスを履歴に保存

標準レスポンス
- OpenAIから完全なレスポンスを取得
- チャット履歴に保存
- クライアントに返却

APIエンドポイント

1. ストリームチャット

エンドポイント: /api/similar_products/stream-chat
メソッド: POST
説明: OpenAI APIを使用したストリーミングチャットレスポンスを提供

リクエスト本文:

{
  "thread_id": "string",
  "dataset_id": "integer",
  "base_product_id": "string",
  "content": "string",
  "review_filter_options": {
    "product_ids": ["string"],
    "viewpoint_ids": ["integer"],
    "sentiment_scores": ["integer"],
    "exclude_no_relate_flag": "boolean",
    "start_post_date": "date",
    "end_post_date": "date",
    "common_viewpoint_id": "integer",
    "sub_viewpoint_ids": ["integer"]
  }
}

レスポンス:

Content-Type: text/event-stream
テキストチャンクのストリーミングレスポンス

ステータスコード:

200: 成功
400: 無効なリクエストデータ
404: データセットが見つからない
500: 内部サーバーエラー

2. 標準チャット

エンドポイント: /api/similar_products/standard-chat
メソッド: POST
説明: 標準（非ストリーミング）チャットレスポンスを提供

リクエスト本文: ストリームチャットと同じ

レスポンス:

{
  "content": "string"
}

ステータスコード:

200: 成功
400: 無効なリクエストデータ
404: データセットが見つからない
500: 内部サーバーエラー

3. チャット履歴取得

エンドポイント: /api/similar_products/chat-history/{thread_id}
メソッド: GET
説明: 特定のスレッドのチャット履歴を取得

パラメータ:

thread_id (パス): String - チャットスレッドの一意識別子

レスポンス:

[
  {
    "thread_id": "string",
    "dataset_id": "integer",
    "base_product_id": "string",
    "role": "string",
    "content": "string",
    "created_at": "datetime"
  }
]

ステータスコード:

200: 成功
404: スレッドが見つからない

4. チャット設定取得

エンドポイント: /api/similar_products/chat-settings/{thread_id}
メソッド: GET
説明: 特定のスレッドのチャット設定を取得

パラメータ:

thread_id (パス): String - チャットスレッドの一意識別子

レスポンス:

{
  "id": "integer",
  "thread_id": "string",
  "temperature": "number",
  "model": "string",
  "system_prompt": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}

ステータスコード:

200: 成功
404: チャット設定が見つからない

5. チャット設定更新

エンドポイント: /api/similar_products/chat-settings/{thread_id}
メソッド: PUT
説明: 特定のスレッドのチャット設定を更新

パラメータ:

thread_id (パス): String - チャットスレッドの一意識別子

リクエスト本文:

{
  "thread_id": "string",
  "temperature": "number",
  "model": "string",
  "system_prompt": "string"
}

レスポンス:

{
  "id": "integer",
  "thread_id": "string",
  "temperature": "number",
  "model": "string",
  "system_prompt": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}

ステータスコード:

201: 成功
400: 無効なリクエスト
404: チャット設定が見つからない

6. チャットスレッド取得

エンドポイント: /api/similar_products/chat-threads
メソッド: GET
説明: すべてのチャットスレッドを取得

レスポンス:

[
  {
    "thread_id": "string",
    "dataset_id": "integer",
    "base_product_id": "string",
    "created_at": "datetime"
  }
]

ステータスコード:

200: 成功

7. 追加質問取得

エンドポイント: /api/similar_products/additional-questions/{thread_id}
メソッド: GET
説明: チャット履歴に基づいて提案される追加質問を取得

パラメータ:

thread_id (パス): String - チャットスレッドの一意識別子

レスポンス:

{
  "questions": ["string"]
}

ステータスコード:

200: 成功
404: スレッドが見つからない

データモデル

チャットリクエストスキーマ

{
  "thread_id": "string",
  "dataset_id": "integer",
  "base_product_id": "string",
  "content": "string",
  "review_filter_options": {
    "product_ids": ["string"],
    "viewpoint_ids": ["integer"],
    "sentiment_scores": ["integer"],
    "exclude_no_relate_flag": "boolean",
    "start_post_date": "date",
    "end_post_date": "date",
    "common_viewpoint_id": "integer",
    "sub_viewpoint_ids": ["integer"]
  }
}

チャット設定スキーマ

{
  "thread_id": "string",
  "temperature": "number",
  "model": "string",
  "system_prompt": "string"
}

データベーススキーマ

データベーステーブルとリレーションシップ

erDiagram
    similar_product_chat_settings ||--o{ similar_product_chat_histories : has
    datasets ||--o{ similar_product_chat_histories : contains
    analyzed_similar_product_review_sentences ||--o{ similar_product_chat_histories : references

    similar_product_chat_settings {
        bigint id PK
        varchar(100) thread_id
        float temperature
        varchar(50) model
        longtext system_prompt
        timestamp created_at
        timestamp updated_at
    }

    similar_product_chat_histories {
        bigint id PK
        varchar(100) thread_id FK
        bigint dataset_id FK
        varchar(100) base_product_id
        varchar(20) role
        longtext content
        timestamp created_at
    }

    datasets {
        bigint id PK
        varchar(100) name
        timestamp created_at
    }

    analyzed_similar_product_review_sentences {
        bigint id PK
        bigint dataset_id FK
        varchar(100) mall_product_id
        int sentiment_score
        longtext content
        date post_date
        int viewpoint_id
        int sub_viewpoint_id
        int no_relate_flag
    }

テーブル詳細

1. similar_product_chat_settings

説明: 各スレッドのチャット設定を保存

id: 主キー (bigint, 自動増分)
thread_id: チャットスレッドの一意識別子 (varchar(100))
temperature: OpenAI温度パラメータ (float)
model: OpenAIモデル名 (varchar(50))
system_prompt: システムプロンプトテンプレート (longtext)
created_at: レコード作成タイムスタンプ (timestamp, デフォルト: CURRENT_TIMESTAMP)
updated_at: レコード更新タイムスタンプ (timestamp, デフォルト: CURRENT_TIMESTAMP)

インデックス:

PRIMARY KEY (id)
INDEX index_similar_product_chat_settings_on_thread_id (thread_id)

2. similar_product_chat_histories

説明: すべてのチャットメッセージとレスポンスを保存

id: 主キー (bigint, 自動増分)
thread_id: チャット設定への外部キー (varchar(100))
dataset_id: データセットへの外部キー (bigint)
base_product_id: 参照製品ID (varchar(100))
role: メッセージロール (varchar(20)) - system/user/assistant
content: メッセージ内容 (longtext)
created_at: メッセージタイムスタンプ (timestamp, デフォルト: CURRENT_TIMESTAMP)

3. datasets

説明: データセット情報を保存

id: 主キー
name: データセット名
created_at: データセット作成タイムスタンプ

4. analyzed_similar_product_review_sentences

説明: チャットコンテキストに使用される分析済み製品レビューを保存

id: 主キー
dataset_id: データセットへの外部キー
mall_product_id: 製品識別子
sentiment_score: レビュー感情スコア
content: レビュー内容
post_date: レビュー投稿日
viewpoint_id: レビュー観点識別子
sub_viewpoint_id: レビューサブ観点識別子
no_relate_flag: 無関係なレビューのフラグ

主要なリレーションシップ

チャット設定とチャット履歴 (1:多)
- 1つのチャット設定は複数のチャット履歴エントリを持つことができる
- thread_idでリンク
データセットとチャット履歴 (1:多)
- 1つのデータセットは複数のチャット履歴エントリを持つことができる
- dataset_idでリンク
データセットとレビュー文 (1:多)
- 1つのデータセットは複数のレビュー文を持つことができる
- dataset_idでリンク

データフロー

新しいチャットが開始されるとき:
- similar_product_chat_settingsにエントリを作成
- 初期システムプロンプトがsimilar_product_chat_historiesに保存される
チャット中:
- ユーザーメッセージがsimilar_product_chat_historiesに保存される
- analyzed_similar_product_review_sentencesからのレビューがコンテキストとして使用される
- AIレスポンスがsimilar_product_chat_historiesに保存される
チャット設定:
- similar_product_chat_settingsで更新可能
- スレッド内の後続のすべてのメッセージに影響する

設定

システムは.envファイルで設定されたOpenAI APIキーを必要とします:

OPENAI_API_KEY=your_api_key

01.aichat-apianalyzer

AIチャット機能ドキュメント

目次

概要

システムアーキテクチャ

1. ストリームチャットフロー

2. 標準チャットフロー

3. データ処理フロー

4. エラー処理フロー

主要コンポーネントの相互作用

パフォーマンスに関する考慮事項

コアコンポーネント

1. サービスレイヤー

2. データアクセスレイヤー

詳細プロセスフロー

チャットリクエスト処理

レスポンス処理

APIエンドポイント

1. ストリームチャット

2. 標準チャット

3. チャット履歴取得

4. チャット設定取得

5. チャット設定更新

6. チャットスレッド取得

7. 追加質問取得

データモデル

チャットリクエストスキーマ

チャット設定スキーマ

データベーススキーマ

データベーステーブルとリレーションシップ

テーブル詳細

1. similar_product_chat_settings

2. similar_product_chat_histories

3. datasets

4. analyzed_similar_product_review_sentences

主要なリレーションシップ

データフロー

設定