外部大規模モデル連携 - Udesk

外部大規模言語モデル連携

Udesk外部インテリジェントエージェントChatインターフェース標準

インターフェース詳細

項目	説明
転送方式	HTTPS
リクエストURL
呼び出し方式	同期呼び出し、モデルの実行完了を待ち最終結果を返す
文字エンコーディング	UTF-8
インターフェースリクエスト形式	JSON
レスポンス形式	JSON
インターフェースリクエストタイプ	POST
開発言語	HTTPSリクエストを発行できる任意の開発言語

リクエストパラメータ

リクエストフィールド

パラメータ名	パラメータ説明	必須	データ型
chatId	セッションID（対応するセッションIDは呼び出し元が生成）	true	number
im_robot_log_id	ロボットメッセージID	true	number
messages	ユーザーメッセージ	true	array
messages[].content	対話内容	true	string
messages[].type	タイプ(text)	true	string
businessData	業務データ	false	jsonObject
stream	ストリーミングかどうか（true: ストリーミング, デフォルトはストリーミングのみサポート）	true	boolean
userId	ユーザーID(対応するcustomer_token)	true	number
sign	Udesk署名	true	string
timestamp	タイムスタンプ	true	long

リクエスト例

{
  "chatId": 714731010,
  "im_robot_log_id": 4740181939,
  "messages": [
    {
      "content": "こんにちは",
      "type": "text"
    }
  ],
  "businessData": {
      "dialogueDesc":"P1234567",
      "nickName":"ゴールドメンバー",
      "customerId":"abc123456",
      "sourcePlugin":"2437",
      "customer_token":"123456"
  },
  "stream": true,
  "userId": 4842328052,
  "sign": "1e18abb8c62ebcc80148026888d28585",
  "timestamp": 1732796173
}

レスポンスパラメータ

1. ストリーミング出力

初期のストリーミング形式の返却、最後の終了メッセージのdataオブジェクトは以下の2.オブジェクト例を参照

パラメータ名	パラメータ説明	型
type	ストリーミング状態：成功/終了/エラー	string
content_chunk	ストリーミング内容：markdown形式をサポート	string
##### ストリーミング状態の説明

SUCCESS: 正常に返却（ストリーミング出力）
END: 対話終了（choiceパラメータは同期インターフェースの返却を参照）
SENSITIVENESS: 機密情報（受信後、それまでのストリーミング出力内容をクリアしてください）
ERROR: アラートラベル（受信後、それまでのストリーミング出力内容をクリアしてください）

レスポンス例（ストリーミング）

data:{"type":"SUCCESS", "content_chunk": "こんにちは"}

data:{"type":"SUCCESS", "content_chunk": "！\n\n"}

...

data:{"type":"SUCCESS", "content_chunk": "教えてください"}

data:{"type":"ERROR", "content_chunk": "エラー内容"}

data:{"type":"END", "content_chunk":"","data": "以下の'2. オブジェクト例'のdataフィールドを参照","usage": {"execution_time": 500}}

2. オブジェクト例

パラメータ名	パラメータ説明	型
data	返却データ本体	object
data.message	返却メッセージ	object
data.message.content	返却内容、typeがimageの場合は画像リンク	string
data.message.type	メッセージタイプ	string
data.cardInfo	カード情報	object
data.imageData	画像データ、urlまたはbase64	string
data.html	htmlタグ	string
data.recommendedList	推奨リスト	list
data.dialogueSlots	対話スロット	object
data.dialogueSlots.dialogueIntent	対話意図(CUSTOMER_SERVICE: オペレーター転送，NULL_ANSWER：ドメイン外拒否応答)	string
data.faqId	FAQ一意ID	string
data.usage	使用量	object
data.usage.executionTime	総所要時間(ミリ秒)	long
data.formId	フォームid	string

オブジェクト例json

{
    "message": {
        "content": "テキストメッセージ：文字列(markdown形式)",
        "type": ""
    },
    "html": "<p>これはリッチテキストです<span>オペレーター</span></p>",
    "recommendedList": [
        {
            "title": "テスト商品一",
            "image": "商品画像リンク",
            "price": "商品価格",
            "description": "商品説明"
        }
    ],
    "cardInfo": {},
    "imageData": "https://ali-pro-km.udeskcs.com/Data/0/oss-km-image/trjH6jpmFpMS8x5m3hnQ3yiRxN8BWaBf/12d50512-478a-4e36-b713-6221365fc717.jpg",
    "dialogueSlots": {
        "dialogueIntent": "CUSTOMER_SERVICE"
    },
    "usage": {
        "executionTime": 1000
    },
    "formId": "フォームid"
}

署名検証スキーム

署名検証フロー

署名検証フローチャート

署名生成方法

メッセージ内容(content)、タイムスタンプ(timestamp)、およびAPIキー(apiKey)に基づいてMD5署名文字列を生成します。

1. パラメータの準備

パラメータ名	型	必須	説明
content	String	はい	ユーザーが入力した元の内容。改行やダブルクォーテーションを含む可能性があります。
timestamp	long	はい	現在のUnixタイムスタンプ（単位：秒）。リプレイ攻撃防止に使用されます。
apiKey	String	はい	事前に割り当てられたAPIキー。署名計算に使用され、機密保持が必要です。長さは128文字以内です。

2. メッセージ内容の前処理

まず、すべての\nを単一のスペースに置き換えます。

content = content.replaceAll("\\n+"," ");

ダブルクォーテーションを以下のように置き換えます。

content = content.replaceAll("\"", "&quot;");

3. 署名文字列の連結

以下の形式で文字列を連結します（注意：apiKeyは末尾に直接連結し、その前に & や他の区切り文字はありません）：

<content>&timestamp=<timestamp><apiKey>

例：現在のタイムスタンプ(timestamp)が 1721620571、contentが "123456"、APIKEYが TEST-aaabbbccc の場合、最終的に連結される文字列は以下のようになります：

content=123456&timestamp=1721620571TEST-aaabbbccc

4. 小文字への変換

前のステップで連結した文字列を小文字に変換します。

例：

String signString = "content=123456&timestamp=1721620571TEST-aaabbbccc".toLowerCase();

5. MD5ハッシュの計算

小文字に変換した文字列に対してMD5ダイジェスト計算を行い、32桁の小文字16進数文字列を出力します。

APIKeyは、顧客の大規模モデルを呼び出すためのaccessTokenです。

sign=md5(content=123456&timestamp=1721620571TEST-aaabbbccc)

md5内の内容を小文字に変換してからMD5暗号化を行います。

重要な注意点：

署名を生成する内容（上記で説明した連結パラメータ、つまり md5() 内の内容）は、UTF-8 エンコーディング形式である必要があります。
内容内の改行はスペースに置き換えられ、複数の改行も1つのスペースに置き換えられます。

署名検証フローチャート

UDフロントエンド

内容 content を渡します。

UDバックエンド

署名生成方法に従って署名を生成し、署名 sign とタイムスタンプ timestamp を返します。

顧客側

APIリクエストボディに追加する必要があるパラメータ：

パラメータ名	パラメータ説明	型
timestamp	タイムスタンプ。署名の有効期限を検証するために使用されます。	number
sign	署名	string

上記の方法に従って署名を検証します：

署名検証成功：実際のデータを返します。
署名検証失敗："署名検証失敗"を示すフラグフィールドを返します。
署名期限切れ：タイムスタンプが期限切れの場合（有効期間は30分）、"署名期限切れ"を示すフラグフィールドを返します。

注意事項

非ストリーミング呼び出しは現在サポートされていません。リクエスト例のstreamパラメータは、UDがデフォルトでtrueを渡しますリクエストパラメータ
顧客側が提供する大規模モデル呼び出しアドレスはHTTPSプロトコルを使用する必要があります
顧客側インターフェースはクロスオリジン問題を処理する必要があります
ストリーミング出力はデフォルトでSSE技術による解析を実装しています
人間への転送要件については、オブジェクト例のdata.dialogueSlots.dialogueIntentフィールドの説明を参照してください

サポートするメッセージタイプ

メッセージタイプ	説明	処理方法
テキスト	リッチテキストをサポート	直接サポート
画像	サポート（リッチテキスト）	直接サポート
音声	IMでテキストに変換され、最終的にリッチテキストになります	テキストに変換して処理
添付ファイル	リッチテキスト	リッチテキストに変換して処理

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search