# 示例 – 为 OpenAI 分析连接器创建负载脚本和图表表达式

这些示例教您如何使用 OpenAI 分析连接器与大型语言模型进行交互。这些示例将指导您完成基本练习，向您展示如何将 AI 生成的文本内容合并到数据模型和图表表达式中。

在这些示例中，您将使用 OpenAI 分析连接器的 OpenAI 聊天补全 API 配置。

您也可以使用 Azure OpenAI 连接器完成此示例。当使用该连接器时，您可以通过 OpenAI 平台而不是 Microsoft Azure 平台与模型进行交互。

## 在您开始之前

在完成此示例之前，您需要完成以下步骤。

* 创建一个 OpenAI 平台帐户

* 获取 OpenAI 密钥

* 启用分析连接功能于 Qlik Cloud

* 使用适用的连接器配置创建连接

有关更多信息，请参阅：

* [设置您的 OpenAI 平台帐户和 Qlik Cloud 环境](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/ac-openai-tutorial.htm#Set)

* [创建连接](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/ac-openai-tutorial.htm#Create)

## 在加载脚本中使用 OpenAI 连接器

创建一个新的 Qlik Sense 应用程序，您将在其中添加一个加载脚本，以便与 OpenAI 平台进行通信。使用此脚本加载的表将在您的应用程序的数据模型中可访问。

遵照下面的步骤。有关额外详细信息，请参阅[从 OpenAI 连接选择并加载数据](https://help.qlik.com/zh-CN/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 加载语句

下一步是创建另一个加载语句来与 OpenAI 通信。使用此语句加载的表指向用于发送请求数据的表和字段的名称。简而言之，脚本正在加载第二个表，以提供 OpenAI 对您的请求项的响应。

要生成脚本的这一部分，可以使用正在使用的连接的选择数据向导。这将生成一个模板脚本，其中包括您提供的属性的名称。或者，您可以在不使用向导的情况下将此表手动添加到脚本编辑器中。

在数据加载编辑器的数据源面板中找到正在使用的连接，然后单击 the 选择数据 icon。这将打开向导。

数据加载编辑器中分析连接的选择数据按钮

数据加载编辑器中分析连接的选择数据按钮

数据加载编辑器中分析连接的选择数据选择数据按钮 ![数据加载编辑器的“添加数据”选项卡，带有“选择数据”图标的标注](https://help.qlik.com/zh-CN/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-CN/cloud-services/Subsystems/Hub/Content/Resources/Images/ui_gen_openai_connection_select-data_wizard_chat.png)

单击插入脚本时，新表将添加到加载脚本中。

现在添加了 OpenAI 加载语句，您的加载脚本应该如下所示：

```
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);
```

信息注释为了使此代码在您的应用程序中正确运行，您的 OpenAI 连接还必须配置与上述加载脚本中 `connectionname` 指定的名称值相同的名称值。有关用于本教程的值，请参阅[创建连接](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/ac-openai-tutorial.htm#Create)。

您现在可以运行加载脚本了。

### 将数据加载到应用程序中

脚本完成后，单击加载数据。这将执行与 OpenAI 的通信，并将表格插入到您的应用程序的数据模型中。

信息注释如果在加载脚本时收到错误，则可能是连接配置中的可选第二关联字段与加载脚本不匹配。如果在连接的配置中定义了关联字段，请确保该字段也包含在请求脚本中。

打开数据模型查看器，注意这两个表按预期链接在一起。在预览窗格中，OpenAI 对我们提出的问题的回答包含在第二个表格中。

从 OpenAI 连接创建的数据模型

从 OpenAI 连接创建的数据模型

从 OpenAIOpenAI 连接创建的数据模型 ![数据模型查看器显示生成的数据模型，其中包括两个表。](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Resources/Images/ui_gen_openai_connection_data_model_chat.png)

您现在可以使用已加载到应用程序中的数据生成分析内容。在使用此数据创建的任何图表中，您都无需引用 OpenAI 连接。要了解如何在图表表达式中直接使用 OpenAI 连接（而不是在加载脚本中使用），请参阅[在图表表达式中使用 OpenAI 连接器](https://help.qlik.com/zh-CN/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-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/ac-openai-use.htm)。

### 数据请求量的注意事项

建议只在一行或几行数据的图表表达式中使用 OpenAI 连接。OpenAI不建议使用图表表达式向 OpenAI 发送大量数据。

了解每个请求发送的行数非常重要。在图表表达式中配置 Azure OpenAI 连接的错误可能会导致意外的大型请求（例如，由于图表中数据模型的使用不当，导致具有相同问题的相同行）。在与第三方平台交互之前，请确保您了解图表表达式计算中使用的字段及其在数据模型中的位置如何影响您与第三方的财务协议和计费安排。外部平台的使用率越高，所产生的成本就越高。

请遵循以下指导原则来缓和和限制您的请求大小：

* 使用图表表达式时，仅使用 Text 对象中的连接（来自 Dashboard bundle）。强烈建议在表对象中使用 OpenAI 连接，尤其是当您将表达式添加到已添加一个或多个维度的表中时。

* 如果图表表达式链接到应用程序的数据模型，请在表达式中使用 if 语句，仅在应用程序中进行单个选择时计算图表。这大大减少了图表将发送到 OpenAI 的请求中的行数。

* 如果您使用 OpenAI 连接发送大型请求，请在加载脚本中使用该连接，而不是在图表表达式中使用，以便将数据预加载到数据模型中。OpenAI

### 练习：创建基本图表表达式

执行以下操作：

1. 创建一个 Qlik Sense 应用程序，并在编辑模式下打开一个新工作表。

   信息注释您用于图表表达式的分析连接需要已在创建应用程序的空间中创建。您可以在应用程序中的数据加载编辑器中执行此操作，也可以从 Analytics 活动中心的“创建”页面执行此操作。有关更多信息，请参阅[创建 OpenAI 连接](https://help.qlik.com/zh-CN/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-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/ac-openai-use.htm#Quick)。

   信息注释为了使此代码在您的应用程序中正确运行，您的 OpenAI 连接还必须配置与表达式中 `connectionname` 指定的名称值相同的名称值。有关用于本教程的值，请参阅[创建连接](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/ac-openai-tutorial.htm#Create)。

6. 单击应用。

Qlik Sense带有 OpenAI 响应的文本对象

Qlik Sense带有 OpenAI 响应的文本对象

Qlik SenseQlik Sense带有 OpenAIOpenAI 响应的文本文本对象 ![带有 OpenAI 响应的 Qlik Sense 工作表对象。](https://help.qlik.com/zh-CN/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-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/ac-openai-tutorial.htm#Create)。

10. 单击应用。

11. 重新调整这些输入和响应框的大小以满足您的需求。

您现在应该可以退出编辑模式并在输入框中键入问题。当您按 Enter 键或单击工作表上的其他任何位置时，答复框将填充来自 OpenAI 的答复。

简单的工作表，带有通用数据和向 OpenAI 提问的输入框

简单的工作表，带有通用数据和向 OpenAI 提问的输入框

简单的工作表，带有通用数据和向 OpenAIOpenAI 提问的输入框 ![带有 OpenAI 响应的 Qlik Sense 工作表对象。](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Resources/Images/ui_gen_openai_simple_text-input.png)

本练习中的 OpenAI 连接根本不与应用程序的数据模型通信，但可以创建更复杂的应用程序，这些应用程序与加载到应用程序中的数据完全集成，并响应您在应用程序中做出的选择。

有关使用变量的更多信息，请参阅[创建变量](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/Variables/create-variable-using-dialog.htm)和[变量输入控件](https://help.qlik.com/zh-CN/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-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/sse-syntax.htm)。

## 了解详情

* [服务器端扩展语法](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/LoadData/sse-syntax.htm)
* [GetSelectedCount - 图表函数](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/ChartFunctions/FieldFunctions/getselectedcount.htm)
* [在表达式中使用变量](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/Variables/work-with-variables.htm)