既存システムにAI機能を後付けするときの連携設計

すでに動いている業務システムに、文章の自動生成のようなAI機能を足す案件の話です。難所はAIそのものではなく、既存側と新しい処理をどうつなぐかにあります。

問題

生成処理は1回あたり数十秒かかることがあります。既存の画面から「押したら結果が返るまで待つ」形で呼ぶと、こうなります。

つなぐ方式を決めないまま実装を始めると、この4つは必ず出ます。

仕組み

新旧をつなぐときに決めることは4点です。

生成処理のように時間がかかるものは、依頼して後で受け取る方式が基本です。既存側は「依頼を登録する」「状態を問い合わせる」の2つを呼ぶだけになり、待ち時間の問題が構造的に消えます。

やること

1. 依頼と受け取りを分ける

処理の流れを3段階にします。

1. 既存側から生成の依頼を登録します。すぐに受付番号が返ります
2. 生成側は裏側で処理し、状態を「処理中」「完了」「失敗」で持ちます
3. 既存側は受付番号で状態を問い合わせるか、完了時に通知を受け取ります

画面は「作成中です」と表示して先に進める作りにします。

2. 入出力の定義を1か所に集める

項目名、型、必須かどうかを一覧にし、両チームが同じものを見る状態にします。仕様書を別々に管理すると、項目名の食い違いが必ず起きます。API定義を自動で出力できる仕組みがあるなら、それを唯一の正とします。

3. エラーを分類して返す

生成側で起きる失敗を、既存側が判断できる分類に置き換えます。

4. 重複を防ぐ

依頼ごとに識別子を付け、同じ識別子の依頼が来たら新規生成せず前回の結果を返します。二重押しと再送の両方をこれで防げます。

5. 記録を残す

どの依頼で、どの版の指示文を使い、何秒かかり、どういう結果になったかを記録します。この記録が後の改善作業の材料になります。

失敗例

まとめ

• 時間のかかる処理は依頼と受け取りを分けます
• 入出力の定義は1か所に集め、それを正とします
• 失敗は分類して返し、対応を決めておきます
• 依頼ごとの識別子で二重生成を防ぎます
• 記録を最初から残します

後から足す機能ほど、つなぎ目の設計で品質が決まります。