OpenAIコネクタ構成ガイド

AIコネクタの動作概要とAIコネクタまたはTealium機能を使用するタイミングに関するガイダンスについては、AIコネクタとTealium機能を参照してください。

動作方法

このコネクタは、カスタムプロンプトとマップされたTealiumデータを使用してOpenAIモデルを呼び出し、その後、リアルタイムでデータをエンリッチするためにJSONイベントとしてTealium Collectにレスポンスを送信します。

ターゲット指定された高価値のインタラクションにOpenAIコネクタを使用し、高ボリュームのイベントでは使用しないでください。過度の使用は、OpenAIアカウントでのレート制限やAPIコストの増加につながり、受信Tealiumイベントボリュームを増加させる可能性があります。

使用とコストの考慮事項

OpenAIコネクタを有効にする前に、OpenAIアカウントの制限、使用層、および価格モデルを確認してください。コネクタは、イベントとオーディエンストリガーに応じて高いリクエストボリュームを生成する可能性があり、予期しない使用や超過コストが発生する可能性があります。

詳細については、OpenAI Developers: Rate limitsを参照してください。

主な考慮事項

• 使用層とレート制限
  OpenAIは、アカウント層に基づいてレート制限を実施しており、分あたりのリクエスト数とトークン数で測定されます。高頻度のイベントや大規模なオーディエンスはすぐにこれらの制限に達し、スロットリングやリクエストの失敗を引き起こす可能性があります。
• 価格とトークン消費
  OpenAIは、モデルによって処理される入力トークンと出力トークンの数に基づいて課金します。長いプロンプト、大きなペイロード、高容量モデルはリクエストごとのコストを増加させます。使用する予定の特定のモデルの価格を確認してください。
• 月間支出と予算管理
  予定外の支出を防ぐために、OpenAIアカウントで使用上限またはアラートを構成します。制限が構成されていない場合、自動化されたワークフローは大きなコストを蓄積する可能性があります。
• トリガーボリューム
  ページビューなどの高ボリュームで低価値のイベントにコネクタを接続することは避けてください。意味のある顧客アクションを表すイベントやオーディエンスを使用し、管理可能な頻度で発生するものを選択してください。

ベストプラクティス

このコネクタから最大の価値を得るために、効果的なソリューションを構築するための以下のガイドラインに従ってください：

• 高価値のトリガー：エンリッチされたコンテキストまたは意味のある顧客入力を含むイベントフィードまたはオーディエンストリガーを選択します。高ボリュームの使用例でこのコネクタをトリガーすると、OpenAIアカウントで追加のコストが発生するか、リクエストが失敗する可能性があります。
• 具体的に：モデルが各出力フィールドをどのように評価し、決定するかについての詳細を含めます。
• プロンプトパラメーター：Tealium属性をプロンプトパラメーターセクションのプレースホルダー名にマップし、プロンプトで二重中括弧を使用してそれらを参照します。たとえば、属性をプレースホルダーproduct_idにマップする場合、プロンプトに{{product_id}}と書きます。

API情報

このコネクタは次のベンダーAPIを使用します：

• API名：OpenAI API
• APIバージョン：v1
• APIエンドポイント：https://api.openai.com/v1
• ドキュメント：OpenAI API

構成

コネクタマーケットプレースにアクセスして新しいコネクタを追加します。コネクタを追加する一般的な手順については、コネクタについてを参照してください。

コネクタを追加した後、次の構成を構成します：

• APIキー：リクエストを認証するために使用されるOpenAI APIキー。キーには、AllまたはRestrictedのいずれかの許可でレスポンス（モデル推論）を作成する権限が必要です。Read Onlyの許可では使用できません。詳細については、OpenAI: APIキーの権限を割り当てるを参照してください。

アクション

アクション名	AudienceStream	EventStream
OpenAIへのプロンプト送信	✓	✓
OpenAIへのプロンプト送信（非推奨）	✓	✓

OpenAIへのプロンプト送信

このアクションは、カスタムプロンプトとマップされたTealiumデータをOpenAIモデルに送信します。コネクタは構造化されたJSON出力をTealium Collectに送信してリアルタイムでデータを豊かにします。

パラメータ

パラメータ	説明
モデル	このプロンプトに使用するOpenAIモデルを選択します。たとえば、gpt-4.1-miniまたはgpt-4.1。 パフォーマンスとコスト要件に合った構造化出力（JSON）に最適化されたモデルの使用を推奨します。

Tealiumコンテキスト

コネクタは自動的にTealium識別子（tealium_account、tealium_profile、tealium_visitor_id）をAIモデルに送信されるプロンプトおよび構造化出力スキーマに含めます。これらの値は現在のイベントから取得されます。プロンプトでこれらを参照する必要はありません。

このマッピングセクションを使用して、必要なtealium_event値を構成し、必要に応じてデフォルトの識別値を上書きします。

ベンダーパラメータ	説明
Tealiumイベント	(必須) AIレスポンスに含まれるtealium_event値。コネクタはこのイベント名を使用してAI結果をTealiumに戻します。
Tealiumデータソース	このコネクタに関連付けられたデータソースキー。
Tealiumアカウント	アカウント値を上書きします。デフォルトは現在のイベント値です。
Tealiumプロファイル	プロファイル値を上書きします。デフォルトは現在のイベント値です。
Tealium訪問ID	訪問IDを上書きします。デフォルトは現在のイベント値です。

プロンプトパラメータ

このマッピングセクションを使用して、プロンプトにTealium属性値を渡します。左の列にTealium属性をマップし、右の列にプレースホルダー名をマップします。プロンプトフィールドでプレースホルダー名を二重中括弧を使用して参照します。

たとえば、属性product_review_textをプレースホルダー名review_textにマップする場合、ランタイムで属性値を挿入するためにプロンプトに{{review_text}}と書きます。

イベントペイロード

イベントペイロードを追加を有効にすると、プロンプトテンプレートに完全なイベントペイロードを{{event_payload}}として含めます。

プロンプト

選択したモデルに送信するプロンプトを入力します。

• マップされたプレースホルダー名を二重中括弧を使用して参照します。たとえば、{{review_text}}、{{product_name}}など。
• イベントペイロードを追加を有効にした後、{{event_payload}}を参照します。
• モデルが各出力フィールドをどのように決定し構成するかを説明します。
• JSONフォーマットの指示を含めないでください（たとえば、「JSONのみを返す」という指示）。コネクタは構造化出力マッピングを通じて自動的にJSON構造を強制します。

高度なモデル構成

パラメータ	説明
temperature	ランダム性と創造性を制御します。
max_output_tokens	モデルが生成できるトークンの最大数。
max_tool_calls	レスポンスで処理される組み込みツール呼び出しの最大数。
top_p	上位p確率質量からのみサンプリングすることで多様性を制御します。
parallel_tool_calls	モデルがツール呼び出しを並行して実行するかどうか。デフォルトはtrueです。
prompt_cache_key	類似のリクエストに対するレスポンスをキャッシュするためにOpenAIが使用するキー。キャッシュ率を最適化します。
service_tier	リクエストの処理に使用される処理タイプを指定します。
tool_choice	モデルがレスポンスを生成する際に使用するツール（またはツール群）を選択する方法を制御します。

構造化出力（JSONスキーマ）

このセクションでは、AIモデルが応答で返すフィールドを定義します。他のマッピングセクションとは異なり、構造化出力ではTealiumの属性をマッピングしません。代わりに、出力フィールド名、データ型、必須かどうかを定義します。

コネクタはこれらの定義をtext.formatを使用してOpenAIにJSONスキーマとして送信します。これにより、モデルは自由形式のテキストではなく、スキーマに合った構造化されたJSONを返す必要があります。その後、コネクタは応答を解析し、イベントとしてTealium Collectに転送します。少なくとも1つのフィールドを定義する必要があります。

スキーマには自動的にTealiumのコンテキストフィールドが含まれます：tealium_account、tealium_profile、tealium_visitor_id、tealium_event。

各行は3つの入力で1つの出力フィールドを定義します：

入力	説明
必須 / 任意	モデルがこのフィールドを返すことを要求するには必須を選択します。スキーマにフィールドを含めるが要求はしない場合は任意を選択します。デフォルトは必須です。
データ型	出力フィールドのデータ型：string、integer、number、またはboolean。デフォルトはstringです。データ型はモデルに値の形式を指示します。型が一致しない場合、検証が失敗する可能性があります。
属性名	出力フィールドの名前。この名前はJSON応答のキーとして表示されます。値をエンリッチメントのためにキャプチャするために、一致するイベント属性を作成します。

デバッグモード

デバッグモードを有効にするを選択して、Tealium Collectに転送することなく生のOpenAI応答を受け入れます。完全な処理を有効にする前に、Traceを使用して応答形式を検証します。

例：レビュー感情の分類

この例は、顧客の製品レビュー感情を分類する構成されたアクションを示しています。

トリガー：product_review_submittedイベントが発生するとイベントフィードが起動します。

Tealiumコンテキスト：

イベント属性	ベンダーパラメータ
ai_response	Tealiumイベント

プロンプトパラメータ：

Tealium属性	プレースホルダー名
product_review_text	review_text
product_name	product_name

イベントペイロード：無効。

プロンプト：

{{product_name}}についてのレビューが顧客によって提出されました：

{{review_text}}

顧客の感情を「不満足」、「中立」、または「満足」として分類します。信頼スコアは0から1の間で提供してください。

構造化出力（JSONスキーマ）：

必須 / 任意	データ型	属性名
必須	string	ai_review_sentiment
必須	number	ai_confidence_score

結果：コネクタはtealium_event: "ai_response"、ai_review_sentiment、およびai_confidence_scoreを含むJSONイベントをTealium Collectに返します。これらの値をキャプチャするために一致するイベント属性を作成します。