# 範例 – 為 OpenAI 分析連接器建立載入指令碼和圖表運算式

這些範例教您如何使用 OpenAI 分析連接器與大型語言模型互動。這會透過基本練習引導您，向您呈現如何在資料模型和圖表運算式中納入 AI 產生的文字內容。

在這些範例中，您將使用 OpenAI 分析連接器的 OpenAI 聊天完成 API 設定。

您也可以使用 Azure OpenAI 連接器完成此範例。使用該連接器時，您會透過 Microsoft Azure 平台與模型互動，而非透過 OpenAI 平台。

## 開始之前

您需要先完成下列步驟，才能完成此範例。

* 建立 OpenAI 平台帳戶

* 取得 OpenAI API 金鑰

* 啟用分析連線功能於 Qlik Cloud

* 以適用的連接器設定建立連線

如需詳細資訊，請參閱：

* [設定您的 OpenAI 平台帳戶和 Qlik Cloud 環境](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/ac-openai-tutorial.htm#Set)

* [建立連線](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/ac-openai-tutorial.htm#Create)

## 在載入指令碼中使用 OpenAI 連接器

建立新的 Qlik Sense 應用程式，您將會對此新增載入指令碼，以與 OpenAI 平台通訊。您透過此指令碼載入的表格將可在應用程式的資料模型中存取。

按照以下步驟。如需其他詳細資訊，請參閱 [從 OpenAI 連線中選取和載入資料](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/ac-openai-load.htm)。

### 建立要傳送至 OpenAI 的資料表格

第一步是建立表格，其中包含您正傳送至 OpenAI 的請求。請求中的資料列稱為「完成」。表格的單一欄位 (欄) 中必須包含每個項目的文字作為列。此欄的每列呈現要透過 OpenAI API 完成的文字。

對於關聯欄位可以有附加的次要欄位，但這需要符合設定中指定的欄位名稱。此為特殊欄位，不會傳送至 OpenAI，但附加至回應，以用於產生 Qlik 資料模型。

在應用程式中，開啟資料載入編輯器並在新的指令碼區段中貼上下列代碼：

```
SourceTable:
NoConcatenate
LOAD 
RowNo() as RowId,
Text
Inline
[Text
translate from English to French: What is the time you go to work?];					
```

此表格包含稱為 `Text` 的欄位，這包含我們向 OpenAI 詢問的單一問題。其他問題可在現有問題的儲存格之下新增為新的個別儲存格。`RowId` 欄位是關聯欄位，這將用於下一步，以將回應連結至應用程式的資料模型。

### 建立 OpenAI LOAD 陳述式

下一步是建立另一個載入陳述式，以與 OpenAI 通訊。您透過此陳述式載入的表格指向您正用來傳送請求資料的表格和欄位名稱。簡言之，正在透過指令碼載入第二表格，以向請求項目提供 OpenAI 的回應。

若要產生此指令碼部分，您可以為正在使用的連線使用選取資料精靈。這會產生包括您提供之屬性名稱的範本指令碼。或者，您可以在指令碼編輯器中手動新增此表格，而不使用精靈。

在資料載入編輯器的資料來源面板中找到您正在使用的連線，並按一下 the 選取資料 icon。這會開啟精靈。

資料載入編輯器中用於分析連線的選取資料按鈕

資料載入編輯器中用於分析連線的選取資料按鈕

資料載入編輯器中用於分析連線的選取資料選取資料按鈕 ![資料載入編輯器的「新增資料」索引標籤，並標註「選取資料」的圖示](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Resources/Images/ui_gen_analytic_connection_select-data_gui3.png)

使用選取資料精靈時，您需要提供兩個屬性：

* 駐留表格的名稱。此表格具有正傳送至 OpenAI 的問題。在此案例中，這是 `SourceTable`。

* 資料欄位的名稱。此欄位包含正傳送至 OpenAI 的問題。在此案例中，這是 `Text`。

在表格之下，對稱為 openai 的表格按一下核取方塊。

資料載入編輯器中的選取資料精靈

資料載入編輯器中的選取資料精靈

資料載入編輯器中的選取資料選取資料精靈 ![「選取資料」精靈顯示使用者輸入的駐留表格和資料欄位值，以及分析連接器可能傳回的欄清單](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Resources/Images/ui_gen_openai_connection_select-data_wizard_chat.png)

按一下插入指令碼時，新的表格會新增至載入指令碼。

現在新增了 OpenAI LOAD 陳述式後，載入指令碼看起來應如下所示：

```
SourceTable:
NoConcatenate
LOAD 
RowNo() as RowId,
Text
Inline
[Text
translate from English to French: What is the time you go to work?];

[openai]:
LOAD
[id],
[object],
[created],
[model],
[prompt_tokens],
[completion_tokens],
[total_tokens],
[choices.message.role],
[choices.message.content],
[choices.index],
[choices.finish_reason],
[RowId]
EXTENSION endpoints.ScriptEval('{"RequestType":"endpoint", "endpoint":{"connectionname":"OpenAI_Examples_Intro"}}', SourceTable);
```

資訊備註為了讓此確切程式碼在應用程式中順暢運作，也必須使用與以上載入指令碼中指定的 `connectionname` 相同的名稱值設定您的 OpenAI 連線。關於用於本教學課程的值，請參閱 [建立連線](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/ac-openai-tutorial.htm#Create)。

您現在已準備好執行載人指令碼。

### 將資料載入應用程式

指令碼完成後，按一下載入資料。這執行與 OpenAI 的通訊並在應用程式的資料模型中插入表格。

資訊備註若您在載入指令碼時收到錯誤，可能是連線設定和載入指令碼中選用的次要關聯欄位之間有不相符的情況。若您已在連線設定中定義關聯欄位，確保這也包括在請求指令碼中。

開啟資料模型檢視器並注意兩個表格如預期連結在一起。在預覽窗格中，OpenAI 對我們詢問之問題的回應包括在第二表格中。

從 OpenAI 連線建立的資料模型

從 OpenAI 連線建立的資料模型

從 OpenAIOpenAI 連線建立的資料模型 ![資料模型檢視器顯示產生的資料模型，這包含兩個表格。](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Resources/Images/ui_gen_openai_connection_data_model_chat.png)

您現在可以使用已載入應用程式的資料來產生分析內容。您不需要在任何使用此資料建立的圖表中參考 OpenAI 連線。若要瞭解如何直接在圖表運算式中使用 OpenAI 連線 (而非在載入指令碼中使用)，請參閱 [在圖表運算式中使用 OpenAI 連接器](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/ac-openai-tutorial-example-3.htm#Using)。

## 在圖表運算式中使用 OpenAI 連接器

除了使用載入指令碼將 OpenAI 問題和答案新增至應用程式的資料模型，您也可以直接在應用程式的圖表中執行這些操作。這可以是使用載入指令碼中的表格來與 OpenAI 通訊的替代選項。

會在您和 OpenAI 之間來回傳送單一欄位的資料。在許多情況下，用於載入指令碼連線的程式碼可以重新用於圖表，並具有顯著的差異。

如需其他詳細資訊，請參閱 [在視覺化運算式中使用 OpenAI 連線](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/ac-openai-use.htm)。

### 資料請求量的考慮事項

在圖表運算式中使用 OpenAI 連線建議僅用於一列或幾列資料。不建議使用圖表運算式將大量資料傳送至 OpenAI。

重要的是，應注意您對每個請求傳送多少列。若在圖表運算式中設定 連線時發生錯誤，可能導致意外的大量請求 (例如由於不當使用圖表中的資料模型而出現問題相同的相同列)。在您與第三方平台互動之前，請確認您瞭解欄位在圖表運算式計算的使用方式，及其在資料模型中的位置，會影響與第三方的財務協議和計費安排。較高的外部平台使用率可能會造成較高的費用。

遵守這些準則以節制並限制請求的大小：

* 處理圖表運算式時，僅使用 文字 物件中的連線 (來自 Dashboard bundle)。強烈不建議在表格物件中使用 OpenAI 連線，尤其是若您正在將運算式新增至已新增一個或多個維度的表格。

* 若圖表運算式連結至應用程式的資料模型，請在運算式中使用 if 陳述式，以在應用程式中選取單一選項時僅計算圖表。這會在圖表將傳送至 OpenAI 的請求中大幅降低列數。

* 若您正在使用 OpenAI 連線傳送大量請求，請在載入指令碼 (而非圖表運算式) 中使用連線，讓資料預先載入到資料模型中。

### 練習：建立基本圖表運算式

請執行下列動作：

1. 建立 Qlik Sense 應用程式並在編輯模式中開啟新的工作表。

   資訊備註您用於圖表運算式的分析連線需要已經在建立應用程式的空間中建立。您可以在應用程式內的資料載入編輯器中，或從 分析 活動中心的「建立」頁面進行此事項。如需詳細資訊，請參閱[建立 OpenAI 連線](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/ac-openai-create.htm)。

2. 在資產面板中，開啟 圖表。

3. 在 儀表板物件 下方，將 文字 物件拖曳到工作表上。

4. 在屬性面板中，在資料 > 量值之下，新增量值並按一下 the 運算式 icon 以開啟運算式編輯器。

5. 在運算式編輯器中貼上下列運算式：

   ```
   endpoints.ScriptAggrStr('{"RequestType":"endpoint", "endpoint":{"connectionname":"OpenAI_Examples_Intro","column":"choices.message.content"}}', 'Translate this text from english to spanish: The sun was rising over the new tomorrow with a tinge of excitement.')
   ```

   資訊備註在此範例中，可以接受不使用 `if` 陳述式，因為我們只傳送單一資料列，沒有連線至資料模型。在其他情境中，使用 `if` 陳述式以確保僅在應用程式中選取單一欄位值時計算圖表。如需範例，請參閱 [快速範例](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/ac-openai-use.htm#Quick)。

   資訊備註為了讓此確切程式碼在您的應用程式中順暢運作，您的 OpenAI 連線也必須使用與運算式中指定的 `connectionname` 相同的 名稱值設定。關於用於本教學課程的值，請參閱 [建立連線](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/ac-openai-tutorial.htm#Create)。

6. 按一下套用。

Qlik Sense文字 物件具有 OpenAI 回應

Qlik Sense文字 物件具有 OpenAI 回應

Qlik SenseQlik Sense文字文字 物件具有 OpenAIOpenAI 回應 ![Qlik Sense 工作表物件具有來自 OpenAI 的回應。](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Resources/Images/ui_gen_openai_connection_chart_expression-sheet.png)

### 練習： 使用變數建立文字輸入方塊

或者，您可以使用已在應用程式中建立的變數名稱取代問題字串，允許建立輸入方塊，讓應用程式取用者可以在此輸入自己的問題，不必與運算式互動。

這個簡單的介面可用來透過即時產生的關聯式資訊豐富您的應用程式資料。

請執行下列動作：

1. 建立應用程式並將一些資料和視覺化新增至新的工作表。

2. 按一下 the 變數 icon 以建立變數。對於此練習，提供名稱 vUserQuestion。讓其餘參數空白。

3. 在資產面板中，將變數輸入圖表拖曳至工作表。這位於 the 自訂物件 icon > Qlik 儀表板搭售之下。

4. 在變數輸入圖表的屬性面板中，展開外觀 > 變數。

5. 在名稱之下，選取 vUserQuestion。

6. 在顯示為之下，選取輸入方塊。

7. 在資產面板中，從 the 自訂物件 icon > Qlik 儀表板搭售，將 文字 物件拖曳到工作表上。

8. 在屬性面板中，在資料 > 量值之下，新增量值並按一下 the 運算式 icon 以開啟運算式編輯器。

9. 在運算式編輯器中貼上下列運算式：

   ```
   if(vUserQuestion <> '', endpoints.scriptAggrStr('{"RequestType":"endpoint", "endpoint":{"connectionname":"OpenAI_Examples_Intro","column":"choices.message.content"}}',vUserQuestion))
   ```

   資訊備註為了讓此確切程式碼在您的應用程式中順暢運作，您的 OpenAI 連線也必須使用與運算式中指定的 `connectionname` 相同的 名稱值設定。關於用於本教學課程的值，請參閱 [建立連線](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/ac-openai-tutorial.htm#Create)。

10. 按一下套用。

11. 調整這些輸入和回應方塊的大小，以配合您的需求。

您現在應能夠結束編輯模式並在輸入方塊中輸入問題。按下 Enter 或按一下工作表的任何地方後，回應方塊將會填入來自 OpenAI 的回應。

簡單工作表具有一般資料和輸入方塊，用於向 OpenAI 詢問問題

簡單工作表具有一般資料和輸入方塊，用於向 OpenAI 詢問問題

簡單工作表具有一般資料和輸入方塊，用於向 OpenAIOpenAI 詢問問題 ![Qlik Sense 工作表物件具有來自 OpenAI 的回應。](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Resources/Images/ui_gen_openai_simple_text-input.png)

這項練習中的 OpenAI 連線完全不會與應用程式的資料模型通訊，但可以建立更加純熟、與載入到應用程式中的資料完全整合的應用程式，並回應您在應用程式中進行的選取。

如需更多關於處理變數的資訊，請參閱 [建立變數](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Sense_Hub/Variables/create-variable-using-dialog.htm) 和 [變數輸入控制](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Sense_Hub/Visualizations/DashboardBundle/variable-input.htm)。

### 載入指令碼和圖表運算式程式碼之間的差異

在這些圖表運算式中，我們已在之前的載入指令碼課程中輸入程式碼，供其他用途使用。下列清單醒目提示載入指令碼版本和圖表運算式之間最重要的差異：

* 我們已將 ScriptEval 變更為 ScriptAggrStr。這概述我們正在傳送單一資料列，並預期會傳回單一列。使用像這個案例中的變數或常數等自訂資料時，需要這麼做。「Str」指示我們正在傳送並接收文字值。

* 我們已新增新的屬性 column，值為 choices.message.content。這內嵌於 endpoint 物件內部。需要這些對設定字串的新增內容，才能指定要從連接器傳回哪個欄位。在圖表運算式中，只會使用一個欄位，我們必須指定是哪一個。

如需詳細資訊，請參閱[伺服器端延伸語法](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/sse-syntax.htm)。

## 瞭解更多資訊

* [伺服器端延伸語法](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/sse-syntax.htm)
* [GetSelectedCount - 圖表函數](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Sense_Hub/ChartFunctions/FieldFunctions/getselectedcount.htm)
* [在運算式中使用變數](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Sense_Hub/Variables/work-with-variables.htm)