你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

快速入门:开始使用 Azure OpenAI 助手(预览版)

使用 Azure OpenAI 助手(预览版),可以创建通过自定义说明按需定制和使用高级工具(如代码解释器和自定义函数)增强的 AI 助手。

先决条件

转到 Azure OpenAI Studio

导航到 Azure OpenAI Studio (https://oai.azure.com/),然后使用有权访问 OpenAI 资源的凭据登录。 在登录过程中或登录之后,选择适当的目录、Azure 订阅和 Azure OpenAI 资源。

在 Azure OpenAI Studio 登陆页面中,从左侧导航中的“操场”>“助手(预览版)”启动助手的操场

Azure OpenAI Studio 登陆页的屏幕截图。

操场

借助助手操场,无需运行任何代码,即可浏览、处理原型和测试 AI 助手。 在此页中,可以快速循环访问和试验这些新想法。

并未填写所有值的助手配置屏幕的屏幕截图。

助手设置

使用“助手设置”窗格创建新的 AI 助手或选择现有助手。

Name 描述
助手名称 与特定模型关联的部署名称。
说明 说明类似于系统消息,你可以在其中提供模型指南,以了解其行为方式以及生成响应时应引用的任何上下文。 你可以描述助手的个性,告诉它应该回答什么和不应该回答什么,并告诉它如何设置回复的格式。 还可以提供在回答响应时应采取的步骤示例。
部署 这是设置要与助手一起使用的模型部署的位置。
函数 为模型创建自定义函数定义,以根据规范构建 API 调用和结构数据输出
代码解释器 代码解释器提供对沙盒化 Python 环境的访问权限,该环境可用于允许模型进行测试和执行代码。
文件 最多可以上传 20 个文件,最大文件大小为 512 MB,以便与工具一起使用。

工具

单个助手最多可以访问 128 个工具,包括code interpreter 和通过函数创建的任何自定义工具。

聊天会话

聊天会话也称为助手 API 中的线程,是用户和助手之间的对话发生的位置。 与传统聊天完成调用不同,线程中的消息数没有限制。 助手会自动压缩请求,以适应模型的输入令牌限制。

这也意味着,你不会控制在会话的每个轮次期间传递给模型的令牌数。 管理令牌将被抽象化,并完全由助手 API 处理。

选择“清除聊天”按钮可删除当前对话历史记录。

在文本输入框下方提供了两个按钮:

  • 添加消息而不运行。
  • 添加并运行。

日志

日志可提供助理 API 活动的详细快照。

显示面板

默认情况下提供三个面板:助手设置、聊天会话和日志。 显示面板允许你添加、删除和重新排列面板。 如果你曾经关闭了某个面板并需要恢复它,请使用“显示面板”还原丢失的面板。

创建第一个助手

  1. 从助理设置下拉列表中,选择“新建”

  2. 为助手命名

  3. 输入以下说明“你是一个 AI 助手,可以编写代码来帮助回答数学问题”

  4. 选择 gpt-4 (1106-preview) 的一个部署。 下拉列表将显示自定义部署名称,因此,如果模型/部署名称不同,则应选择基础模型等效于 1106 预览模型的部署。

  5. 选择启用代码解释器的开关。

  6. 选择“保存”。

    已输入配置详细信息的助手的屏幕截图。

  7. 输入助手要回答的问题:“我需要对公式 3x + 11 = 14 求解。 你可以帮我吗?”

  8. 选择“添加并运行”按钮

    The solution to the equation (3x + 11 = 14) is (x = 1).
    

    虽然我们可以看到答案是正确的,但为了确认模型使用了代码解释器来得出此答案,并且它编写的代码有效,而不仅是重复模型训练数据中的答案,我们将提出另一个问题。

  9. 输入后续问题:“向我显示为获取此答案而运行的代码。”

    Certainly! Here's the Python code I ran to find the solution for the equation (3x + 11 = 14):
    
    from sympy import symbols, Eq, solve  
    
    # Define the variable  
    x = symbols('x')  
    
    # Define the equation  
    equation = Eq(3*x + 11, 14)  
    
    # Solve the equation  
    solution = solve(equation, x)  
    solution  
    

助手操场中对话会话的屏幕截图。

还可以查阅右侧面板中的日志,以确认是否使用了代码解释器,并验证为生成答复而运行的代码。 请务必记住,虽然代码解释器可支持模型通过将问题转换为代码并在沙盒化 Python 环境中运行来回答更复杂的数学问题,但仍需要验证答复,以确认模型是否正确地将问题转换为代码中的有效表示形式。

清理资源

如果你想要清理和删除 OpenAI 资源,可以删除资源或资源组。 删除资源组同时也会删除与之相关联的任何其他资源。

另请参阅

重要

本文介绍的某些功能可能仅在预览版中提供。 此预览版未提供服务级别协议,不建议将其用于生产工作负载。 某些功能可能不受支持或者受限。 有关详细信息,请参阅 Microsoft Azure 预览版补充使用条款

先决条件

  • Azure 订阅 - 免费创建订阅

  • 已在所需的 Azure 订阅中授予对 Azure OpenAI 的访问权限。

    目前,仅应用程序授予对此服务的访问权限。 可以通过在 https://aka.ms/oai/access 上填写表单来申请对 Azure OpenAI 的访问权限。 如果有任何问题,请在此存储库上提出问题以联系我们。

  • 一个部署了模型的 Azure AI 中心资源。 有关模型部署的详细信息,请参阅资源部署指南

  • Azure AI Studio 中的 Azure AI 项目

转到 Azure AI Studio(预览版)

  1. 登录到 Azure AI Studio

  2. 转到你的项目或在 Azure AI Studio 中创建新项目

  3. 从项目概述中,选择位于“项目操场”下的“助手”

    借助助手操场,无需运行任何代码,即可浏览、处理原型和测试 AI 助手。 在此页中,可以快速循环访问和试验这些新想法。

    操场提供了多个用于配置助手的选项。 在以下步骤中,你将使用“助理设置”窗格创建新的 AI 助手。

    Name 描述
    助手名称 与特定模型关联的部署名称。
    说明 说明类似于系统消息,你可以在其中提供模型指南,以了解其行为方式以及生成响应时应引用的任何上下文。 你可以描述助手的个性,告诉它应该回答什么和不应该回答什么,并告诉它如何设置回复的格式。 还可以提供在回答响应时应采取的步骤示例。
    部署 这是设置要与助手一起使用的模型部署的位置。
    函数 为模型创建自定义函数定义,以根据规范构建 API 调用和结构数据输出。 未在本快速入门中使用。
    代码解释器 代码解释器提供对沙盒化 Python 环境的访问权限,该环境可用于允许模型进行测试和执行代码。
    文件 最多可以上传 20 个文件,最大文件大小为 512 MB,以便与工具一起使用。 未在本快速入门中使用。

    “助理配置”屏幕的屏幕截图,其中未填充所有值。

创建第一个助手

  1. 从“部署”下拉列表中选择你的部署。

  2. 从“助手”下拉列表中选择“新建”

  3. 为助手命名。

  4. 输入以下说明“你是一个 AI 助手,可以编写代码来帮助回答数学问题”

  5. 选择模型部署。 建议使用最新 gpt-4 模型之一进行测试。

  6. 选择启用代码解释器的开关。

  7. 选择“保存”。

    已输入配置详细信息的助手的屏幕截图。

  8. 输入助手要回答的问题:“我需要对公式 3x + 11 = 14 求解。 你可以帮我吗?”

  9. 选择“添加并运行”按钮

    The solution to the equation (3x + 11 = 14) is (x = 1).
    

    虽然我们可以看到答案是正确的,但为了确认模型使用了代码解释器来得出此答案,并且它编写的代码有效,而不仅是重复模型训练数据中的答案,我们将提出另一个问题。

  10. 输入后续问题:“向我显示为获取此答案而运行的代码。”

    Sure. The code is very straightforward
    
    # calculation
    x = (14 - 11) / 3
    x
    
    
    First, we subtract 11 from 14, then divide the result by 3. This gives us the value of x which is 1.0.
    

    助手操场中对话会话的屏幕截图。

还可以查阅右侧面板中的日志,以确认是否使用了代码解释器,并验证为生成答复而运行的代码。 请务必记住,虽然代码解释器可支持模型通过将问题转换为代码并在沙盒化 Python 环境中运行来回答更复杂的数学问题,但仍需要验证答复,以确认模型是否正确地将问题转换为代码中的有效表示形式。

关键概念

使用助手操场时,请记住以下概念。

工具

单个助手最多可以访问 128 个工具,包括code interpreter 和通过函数创建的任何自定义工具。

聊天会话

聊天会话也称为助手 API 中的线程,是用户和助手之间的对话发生的位置。 与传统聊天完成调用不同,线程中的消息数没有限制。 助手会自动压缩请求,以适应模型的输入令牌限制。

这也意味着,你不会控制在会话的每个轮次期间传递给模型的令牌数。 管理令牌将被抽象化,并完全由助手 API 处理。

选择“清除聊天”按钮可删除当前对话历史记录。

在文本输入框下方提供了两个按钮:

  • 添加消息而不运行。
  • 添加并运行。

日志

日志可提供助理 API 活动的详细快照。

显示面板

默认情况下提供三个面板:助手设置、聊天会话和日志。 显示面板允许你添加、删除和重新排列面板。 如果你曾经关闭了某个面板并需要恢复它,请使用“显示面板”还原丢失的面板。

清理资源

如果你想要清理和删除 OpenAI 资源,可以删除资源或资源组。 删除资源组同时也会删除与之相关联的任何其他资源。

或者,可以通过助手的 API 删除助手线程

另请参阅

参考文档 | 库源代码 | 包 (PyPi) |

先决条件

对于无密码身份验证,需要

  1. 使用 azure-identity 包。
  2. Cognitive Services User角色分配给用户帐户。 这可以在 Azure 门户的访问控制 (IAM)>添加角色分配下完成。
  3. 使用 Azure CLI(例如,az login)登录。

设置

  1. 使用以下项安装 OpenAI Python 客户端库:
pip install openai
  1. 对于推荐的无密码身份验证:
pip install azure-identity

注意

  • 文件搜索可为每个助手最多引入 10,000 个文件 - 比之前多 500 倍。 它速度快,支持通过多线程搜索进行并行查询,并具有增强的重新排序和查询重写功能。
    • 矢量存储是 API 中的新对象。 文件一旦添加到矢量存储中,就会自动进行分析、分块和嵌入,以便随时搜索。 矢量存储可跨助手和线程使用,简化了文件管理和计费。
  • 我们添加了对 tool_choice 参数的支持,该参数可用于在特定运行中强制使用特定工具(如文件搜索、代码解释器或函数)。

注意

此库由 OpenAI 维护。 请参阅发布历史记录,以跟踪库的最新更新。

检索密钥和终结点

若要成功对 Azure OpenAI 服务发出调用,需要准备好以下各项:

变量名称
ENDPOINT 从 Azure 门户检查资源时,可在“密钥和终结点”部分中找到此值。 也可在“Azure OpenAI Studio”>“操场”>“查看代码”中找到该值。 示例终结点为:https://docs-test-001.openai.azure.com/
API-KEY 从 Azure 门户检查资源时,可在“密钥和终结点”部分中找到此值。 可以使用 KEY1KEY2
DEPLOYMENT-NAME 此值将对应于在部署模型时为部署选择的自定义名称。 此值可在 Azure 门户中的“资源管理”>“模型部署”下,或者在 Azure OpenAI Studio 中的“管理”>“部署”下找到此值。

在 Azure 门户中转到你的资源。 可以在“资源管理”部分中找到“密钥和终结点”。 复制终结点和访问密钥,因为在对 API 调用进行身份验证时需要这两项。 可以使用 KEY1KEY2。 始终准备好两个密钥可以安全地轮换和重新生成密钥,而不会导致服务中断。

Azure 门户中 Azure OpenAI 资源概述边栏选项卡的屏幕截图,其中终结点和访问密钥的位置用红圈标示。

为密钥和终结点创建和分配持久环境变量。

环境变量

为密钥和终结点创建和分配持久环境变量。

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE" 

创建助手

我们将在代码中指定以下值:

Name 描述
助手名称 与特定模型关联的部署名称。
说明 说明类似于系统消息,你可以在其中提供模型指南,以了解其行为方式以及生成响应时应引用的任何上下文。 你可以描述助手的个性,告诉它应该回答什么和不应该回答什么,并告诉它如何设置回复的格式。 还可以提供在回答响应时应采取的步骤示例。
型号 这是设置要与助手一起使用的模型部署名称的位置。 检索工具需要 gpt-35-turbo (1106)gpt-4 (1106-preview) 模型。 将此值设置为部署名称,而不是模型名称,除非它是相同的。
代码解释器 代码解释器提供对沙盒化 Python 环境的访问权限,该环境可用于允许模型进行测试和执行代码。

工具

单个助手最多可以访问 128 个工具,包括code interpreter 和通过函数创建的任何自定义工具。

创建 Python 应用

使用 az login 登录到 Azure,然后使用以下推荐的无密码 Python 示例创建并运行助手:

import os
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import AzureOpenAI

token_provider = get_bearer_token_provider(DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default")

client = AzureOpenAI(
    azure_ad_token_provider=token_provider,
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-05-01-preview",
)

# Create an assistant
assistant = client.beta.assistants.create(
    name="Math Assist",
    instructions="You are an AI assistant that can write code to help answer math questions.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-1106-preview" # You must replace this value with the deployment name for your model.
)

# Create a thread
thread = client.beta.threads.create()

# Add a user question to the thread
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)

# Run the thread and poll for the result
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions="Please address the user as Jane Doe. The user has a premium account.",
)

print("Run completed with status: " + run.status)

if run.status == "completed":
    messages = client.beta.threads.messages.list(thread_id=thread.id)
    print(messages.to_json(indent=2))

要使用服务 API 密钥进行身份验证,可以使用以下 Python 示例创建并运行助手:

import os
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-05-01-preview",
)

# Create an assistant
assistant = client.beta.assistants.create(
    name="Math Assist",
    instructions="You are an AI assistant that can write code to help answer math questions.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-1106-preview" # You must replace this value with the deployment name for your model.
)

# Create a thread
thread = client.beta.threads.create()

# Add a user question to the thread
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)

# Run the thread and poll for the result
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions="Please address the user as Jane Doe. The user has a premium account.",
)

print("Run completed with status: " + run.status)

if run.status == "completed":
    messages = client.beta.threads.messages.list(thread_id=thread.id)
    print(messages.to_json(indent=2))

输出

运行完成,状态为:已完成

{
  "data": [
    {
      "id": "msg_4SuWxTubHsHpt5IlBTO5Hyw9",
      "assistant_id": "asst_cYqL1RuwLyFV3HU1gkaE2k0K",
      "attachments": [],
      "content": [
        {
          "text": {
            "annotations": [],
            "value": "The solution to the equation \\(3x + 11 = 14\\) is \\(x = 1\\)."
          },
          "type": "text"
        }
      ],
      "created_at": 1716397091,
      "metadata": {},
      "object": "thread.message",
      "role": "assistant",
      "run_id": "run_hFgBPbUtO8ZNTnNPC8PgpH1S",
      "thread_id": "thread_isb7spwRycI5ueT9E7357aOm"
    },
    {
      "id": "msg_Z32w2E7kY5wEWhZqQWxIbIUB",
      "assistant_id": null,
      "attachments": [],
      "content": [
        {
          "text": {
            "annotations": [],
            "value": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
          },
          "type": "text"
        }
      ],
      "created_at": 1716397025,
      "metadata": {},
      "object": "thread.message",
      "role": "user",
      "run_id": null,
      "thread_id": "thread_isb7spwRycI5ueT9E7357aOm"
    }
  ],
  "object": "list",
  "first_id": "msg_4SuWxTubHsHpt5IlBTO5Hyw9",
  "last_id": "msg_Z32w2E7kY5wEWhZqQWxIbIUB",
  "has_more": false
}

理解结果

在此示例中,我们将创建一个启用了代码解释器的助手。 当我们向助手提出数学问题时,它会将问题转换为 python 代码,并在沙盒环境中执行代码,以确定问题的答案。 由模型创建并进行测试以得出答案的代码为:

from sympy import symbols, Eq, solve  
  
# Define the variable  
x = symbols('x')  
  
# Define the equation  
equation = Eq(3*x + 11, 14)  
  
# Solve the equation  
solution = solve(equation, x)  
solution  

请务必记住,虽然代码解释器支持模型通过将问题转换为代码并在 Python 沙盒中以迭代方式运行该代码来响应更复杂的查询,直到它得出答案,但仍需对响应进行验证,以确认模型是否已正确地将问题转换为代码中的有效表示形式。

清理资源

如果你想要清理和删除 OpenAI 资源,可以删除资源或资源组。 删除资源组同时也会删除与之相关联的任何其他资源。

另请参阅

参考文档 | 源代码 | 包 (NuGet)

先决条件

设置

创建新的 .NET Core 应用程序

在控制台窗口(例如 cmd、PowerShell 或 Bash)中,使用 dotnet new 命令创建名为 azure-openai-quickstart 的新控制台应用。 此命令将创建包含单个 C# 源文件的简单“Hello World”项目:Program.cs

dotnet new console -n azure-openai-assistants-quickstart

将目录更改为新创建的应用文件夹。 可使用以下代码生成应用程序:

dotnet build

生成输出不应包含警告或错误。

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

使用以下项安装 OpenAI .NET 客户端库:

dotnet add package Azure.AI.OpenAI.Assistants --prerelease

检索密钥和终结点

若要成功对 Azure OpenAI 发出调用,需要一个终结点和一个密钥。

变量名称
ENDPOINT 从 Azure 门户检查资源时,可在“密钥和终结点”部分中找到此值。 或者,可以在“Azure OpenAI Studio”>“操场”>“代码视图”中找到该值。 示例终结点为:https://docs-test-001.openai.azure.com/
API-KEY 从 Azure 门户检查资源时,可在“密钥和终结点”部分中找到此值。 可以使用 KEY1KEY2

在 Azure 门户中转到你的资源。 可在“资源管理”部分中找到“密钥和终结点”部分。 复制终结点和访问密钥,因为在对 API 调用进行身份验证时需要这两项。 可以使用 KEY1KEY2。 始终准备好两个密钥可以安全地轮换和重新生成密钥,而不会导致服务中断。

Azure 门户中 Azure OpenAI 资源概述 UI 的屏幕截图,其中终结点和访问密钥的位置用红圈标示。

环境变量

为密钥和终结点创建和分配持久环境变量。

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE" 

创建助手

我们将在代码中指定以下值:

Name 描述
助手名称 与特定模型关联的部署名称。
说明 说明类似于系统消息,你可以在其中提供模型指南,以了解其行为方式以及生成响应时应引用的任何上下文。 你可以描述助手的个性,告诉它应该回答什么和不应该回答什么,并告诉它如何设置回复的格式。 还可以提供在回答响应时应采取的步骤示例。
型号 这是设置要与助手一起使用的模型部署名称的位置。 检索工具需要 gpt-35-turbo (1106)gpt-4 (1106-preview) 模型。 将此值设置为部署名称,而不是模型名称,除非它是相同的。
代码解释器 代码解释器提供对沙盒化 Python 环境的访问权限,该环境可用于允许模型进行测试和执行代码。

工具

单个助手最多可以访问 128 个工具,包括code interpreter 和通过函数创建的任何自定义工具。

使用以下内容创建并运行助手:

using Azure;
using Azure.AI.OpenAI.Assistants;

string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new ArgumentNullException("AZURE_OPENAI_ENDPOINT");
string key = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY") ?? throw new ArgumentNullException("AZURE_OPENAI_API_KEY");
AssistantsClient client = new AssistantsClient(new Uri(endpoint), new AzureKeyCredential(key));

// Create an assistant
Assistant assistant = await client.CreateAssistantAsync(
    new AssistantCreationOptions("gpt-4-1106-preview") // Replace this with the name of your model deployment
    {
        Name = "Math Tutor",
        Instructions = "You are a personal math tutor. Write and run code to answer math questions.",
        Tools = { new CodeInterpreterToolDefinition() }
    });

// Create a thread
AssistantThread thread = await client.CreateThreadAsync();

// Add a user question to the thread
ThreadMessage message = await client.CreateMessageAsync(
    thread.Id,
    MessageRole.User,
    "I need to solve the equation `3x + 11 = 14`. Can you help me?");

// Run the thread
ThreadRun run = await client.CreateRunAsync(
    thread.Id,
    new CreateRunOptions(assistant.Id)
);

// Wait for the assistant to respond
do
{
    await Task.Delay(TimeSpan.FromMilliseconds(500));
    run = await client.GetRunAsync(thread.Id, run.Id);
}
while (run.Status == RunStatus.Queued
    || run.Status == RunStatus.InProgress);

// Get the messages
PageableList<ThreadMessage> messagesPage = await client.GetMessagesAsync(thread.Id);
IReadOnlyList<ThreadMessage> messages = messagesPage.Data;

// Note: messages iterate from newest to oldest, with the messages[0] being the most recent
foreach (ThreadMessage threadMessage in messages.Reverse())
{
    Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
    foreach (MessageContent contentItem in threadMessage.ContentItems)
    {
        if (contentItem is MessageTextContent textItem)
        {
            Console.Write(textItem.Text);
        }
        Console.WriteLine();
    }
}

这将打印输出,如下所示:

2024-03-05 03:38:17 -       user: I need to solve the equation `3x + 11 = 14`. Can you help me?
2024-03-05 03:38:25 -  assistant: The solution to the equation \(3x + 11 = 14\) is \(x = 1\).

可以在重新运行之前在线程上创建新消息,可以看到助手使用过去的消息作为线程中的上下文。

清理资源

如果你想要清理和删除 OpenAI 资源,可以删除资源或资源组。 删除资源组同时也会删除与之相关联的任何其他资源。

另请参阅

参考文档 | 库源代码 | 包 (npm) |

先决条件

对于无密码身份验证,需要

  1. 使用@azure/identity包。
  2. Cognitive Services User角色分配给用户帐户。 这可以在 Azure 门户的访问控制 (IAM)>添加角色分配下完成。
  3. 使用 Azure CLI(例如,az login)登录。

设置

  1. 使用以下内容安装适用于 JavaScript 的 OpenAI 助手客户端库:

    npm install openai
    
  2. 对于推荐的无密码身份验证:

    npm install @azure/identity
    

检索密钥和终结点

若要成功对 Azure OpenAI 服务发出调用,需要准备好以下各项:

变量名称
ENDPOINT 从 Azure 门户检查资源时,可在“密钥和终结点”部分中找到此值。 也可在“Azure OpenAI Studio”>“操场”>“查看代码”中找到该值。 示例终结点为:https://docs-test-001.openai.azure.com/
API-KEY 从 Azure 门户检查资源时,可在“密钥和终结点”部分中找到此值。 可以使用 KEY1KEY2
DEPLOYMENT-NAME 此值将对应于在部署模型时为部署选择的自定义名称。 此值可在 Azure 门户中的“资源管理”>“模型部署”下,或者在 Azure OpenAI Studio 中的“管理”>“部署”下找到此值。

在 Azure 门户中转到你的资源。 可以在“资源管理”部分中找到“密钥和终结点”。 复制终结点和访问密钥,因为在对 API 调用进行身份验证时需要这两项。 可以使用 KEY1KEY2。 始终准备好两个密钥可以安全地轮换和重新生成密钥,而不会导致服务中断。

Azure 门户中 OpenAI 资源概述边栏选项卡的屏幕截图,其中终结点和访问密钥的位置用红圈标示。

为密钥和终结点创建和分配持久环境变量。

环境变量

为密钥和终结点创建和分配持久环境变量。

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE" 

为部署名称和 API 版本添加其他环境变量:

  • AZURE_OPENAI_DEPLOYMENT_NAME:部署名称,如 Azure 门户中所示。
  • OPENAI_API_VERSION:详细了解 API 版本

为密钥和终结点创建和分配持久环境变量。

setx AZURE_OPENAI_DEPLOYMENT_NAME "REPLACE_WITH_YOUR_DEPLOYMENT_NAME" 
setx OPENAI_API_VERSION "REPLACE_WITH_YOUR_API_VERSION" 

创建助手

我们将在代码中指定以下值:

Name 描述
助手名称 与特定模型关联的部署名称。
说明 说明类似于系统消息,你可以在其中提供模型指南,以了解其行为方式以及生成响应时应引用的任何上下文。 你可以描述助手的个性,告诉它应该回答什么和不应该回答什么,并告诉它如何设置回复的格式。 还可以提供在回答响应时应采取的步骤示例。
型号 这是部署名称。
代码解释器 代码解释器提供对沙盒化 Python 环境的访问权限,该环境可用于允许模型进行测试和执行代码。

工具

单个助手最多可以访问 128 个工具,包括code interpreter 和通过函数创建的任何自定义工具。

使用az login登录到 Azure,然后使用以下推荐的无密码 TypeScript 模块 (index.ts) 创建并运行助手:

import "dotenv/config";
import { AzureOpenAI } from "openai";
import {
  Assistant,
  AssistantCreateParams,
  AssistantTool,
} from "openai/resources/beta/assistants";
import { Message, MessagesPage } from "openai/resources/beta/threads/messages";
import { Run } from "openai/resources/beta/threads/runs/runs";
import { Thread } from "openai/resources/beta/threads/threads";

// Add `Cognitive Services User` to identity for Azure OpenAI resource
import {
  DefaultAzureCredential,
  getBearerTokenProvider,
} from "@azure/identity";

// Get environment variables
const azureOpenAIEndpoint = process.env.AZURE_OPENAI_ENDPOINT as string;
const azureOpenAIDeployment = process.env
  .AZURE_OPENAI_DEPLOYMENT_NAME as string;
const openAIVersion = process.env.OPENAI_API_VERSION as string;

// Check env variables
if (!azureOpenAIEndpoint || !azureOpenAIDeployment || !openAIVersion) {
  throw new Error(
    "Please ensure to set AZURE_OPENAI_DEPLOYMENT_NAME and AZURE_OPENAI_ENDPOINT in your environment variables."
  );
}

// Get Azure SDK client
const getClient = (): AzureOpenAI => {
  const credential = new DefaultAzureCredential();
  const scope = "https://cognitiveservices.azure.com/.default";
  const azureADTokenProvider = getBearerTokenProvider(credential, scope);
  const assistantsClient = new AzureOpenAI({
    endpoint: azureOpenAIEndpoint,
    apiVersion: openAIVersion,
    azureADTokenProvider,
  });
  return assistantsClient;
};

const assistantsClient = getClient();

const options: AssistantCreateParams = {
  model: azureOpenAIDeployment, // Deployment name seen in Azure AI Studio
  name: "Math Tutor",
  instructions:
    "You are a personal math tutor. Write and run JavaScript code to answer math questions.",
  tools: [{ type: "code_interpreter" } as AssistantTool],
};
const role = "user";
const message = "I need to solve the equation `3x + 11 = 14`. Can you help me?";

// Create an assistant
const assistantResponse: Assistant =
  await assistantsClient.beta.assistants.create(options);
console.log(`Assistant created: ${JSON.stringify(assistantResponse)}`);

// Create a thread
const assistantThread: Thread = await assistantsClient.beta.threads.create({});
console.log(`Thread created: ${JSON.stringify(assistantThread)}`);

// Add a user question to the thread
const threadResponse: Message =
  await assistantsClient.beta.threads.messages.create(assistantThread.id, {
    role,
    content: message,
  });
console.log(`Message created:  ${JSON.stringify(threadResponse)}`);

// Run the thread and poll it until it is in a terminal state
const runResponse: Run = await assistantsClient.beta.threads.runs.createAndPoll(
  assistantThread.id,
  {
    assistant_id: assistantResponse.id,
  },
  { pollIntervalMs: 500 }
);
console.log(`Run created:  ${JSON.stringify(runResponse)}`);

// Get the messages
const runMessages: MessagesPage =
  await assistantsClient.beta.threads.messages.list(assistantThread.id);
for await (const runMessageDatum of runMessages) {
  for (const item of runMessageDatum.content) {
    // types are: "image_file" or "text"
    if (item.type === "text") {
      console.log(`Message content: ${JSON.stringify(item.text?.value)}`);
    }
  }
}

要使用服务密钥进行身份验证,可以使用以下 TypeScript 模块 (index.ts) 创建并运行助手:

import "dotenv/config";
import { AzureOpenAI } from "openai";
import {
  Assistant,
  AssistantCreateParams,
  AssistantTool,
} from "openai/resources/beta/assistants";
import { Message, MessagesPage } from "openai/resources/beta/threads/messages";
import { Run } from "openai/resources/beta/threads/runs/runs";
import { Thread } from "openai/resources/beta/threads/threads";

// Get environment variables
const azureOpenAIKey = process.env.AZURE_OPENAI_KEY as string;
const azureOpenAIEndpoint = process.env.AZURE_OPENAI_ENDPOINT as string;
const azureOpenAIDeployment = process.env
  .AZURE_OPENAI_DEPLOYMENT_NAME as string;
const openAIVersion = process.env.OPENAI_API_VERSION as string;

// Check env variables
if (!azureOpenAIKey || !azureOpenAIEndpoint || !azureOpenAIDeployment || !openAIVersion) {
  throw new Error(
    "Please set AZURE_OPENAI_KEY and AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_DEPLOYMENT_NAME in your environment variables."
  );
}

// Get Azure SDK client
const getClient = (): AzureOpenAI => {
  const assistantsClient = new AzureOpenAI({
    endpoint: azureOpenAIEndpoint,
    apiVersion: openAIVersion,
    apiKey: azureOpenAIKey,
  });
  return assistantsClient;
};

const assistantsClient = getClient();

const options: AssistantCreateParams = {
  model: azureOpenAIDeployment, // Deployment name seen in Azure AI Studio
  name: "Math Tutor",
  instructions:
    "You are a personal math tutor. Write and run JavaScript code to answer math questions.",
  tools: [{ type: "code_interpreter" } as AssistantTool],
};
const role = "user";
const message = "I need to solve the equation `3x + 11 = 14`. Can you help me?";

// Create an assistant
const assistantResponse: Assistant =
  await assistantsClient.beta.assistants.create(options);
console.log(`Assistant created: ${JSON.stringify(assistantResponse)}`);

// Create a thread
const assistantThread: Thread = await assistantsClient.beta.threads.create({});
console.log(`Thread created: ${JSON.stringify(assistantThread)}`);

// Add a user question to the thread
const threadResponse: Message =
  await assistantsClient.beta.threads.messages.create(assistantThread.id, {
    role,
    content: message,
  });
console.log(`Message created:  ${JSON.stringify(threadResponse)}`);

// Run the thread and poll it until it is in a terminal state
const runResponse: Run = await assistantsClient.beta.threads.runs.createAndPoll(
  assistantThread.id,
  {
    assistant_id: assistantResponse.id,
  },
  { pollIntervalMs: 500 }
);
console.log(`Run created:  ${JSON.stringify(runResponse)}`);

// Get the messages
const runMessages: MessagesPage =
  await assistantsClient.beta.threads.messages.list(assistantThread.id);
for await (const runMessageDatum of runMessages) {
  for (const item of runMessageDatum.content) {
    // types are: "image_file" or "text"
    if (item.type === "text") {
      console.log(`Message content: ${JSON.stringify(item.text?.value)}`);
    }
  }
}

输出

Assistant created: {"id":"asst_zXaZ5usTjdD0JGcNViJM2M6N","createdAt":"2024-04-08T19:26:38.000Z","name":"Math Tutor","description":null,"model":"daisy","instructions":"You are a personal math tutor. Write and run JavaScript code to answer math questions.","tools":[{"type":"code_interpreter"}],"fileIds":[],"metadata":{}}
Thread created: {"id":"thread_KJuyrB7hynun4rvxWdfKLIqy","createdAt":"2024-04-08T19:26:38.000Z","metadata":{}}
Message created:  {"id":"msg_o0VkXnQj3juOXXRCnlZ686ff","createdAt":"2024-04-08T19:26:38.000Z","threadId":"thread_KJuyrB7hynun4rvxWdfKLIqy","role":"user","content":[{"type":"text","text":{"value":"I need to solve the equation `3x + 11 = 14`. Can you help me?","annotations":[]},"imageFile":{}}],"assistantId":null,"runId":null,"fileIds":[],"metadata":{}}
Created run
Run created:  {"id":"run_P8CvlouB8V9ZWxYiiVdL0FND","object":"thread.run","status":"queued","model":"daisy","instructions":"You are a personal math tutor. Write and run JavaScript code to answer math questions.","tools":[{"type":"code_interpreter"}],"metadata":{},"usage":null,"assistantId":"asst_zXaZ5usTjdD0JGcNViJM2M6N","threadId":"thread_KJuyrB7hynun4rvxWdfKLIqy","fileIds":[],"createdAt":"2024-04-08T19:26:39.000Z","expiresAt":"2024-04-08T19:36:39.000Z","startedAt":null,"completedAt":null,"cancelledAt":null,"failedAt":null}
Message content: "The solution to the equation \\(3x + 11 = 14\\) is \\(x = 1\\)."
Message content: "Yes, of course! To solve the equation \\( 3x + 11 = 14 \\), we can follow these steps:\n\n1. Subtract 11 from both sides of the equation to isolate the term with x.\n2. Then, divide by 3 to find the value of x.\n\nLet me calculate that for you."
Message content: "I need to solve the equation `3x + 11 = 14`. Can you help me?"

请务必记住,虽然代码解释器支持模型通过将问题转换为代码并在 JavaScript 中以迭代方式运行该代码来响应更复杂的查询,直到它得出答案,但仍需对响应进行验证,以确认模型是否已正确地将问题转换为代码中的有效表示形式。

清理资源

如果你想要清理和删除 OpenAI 资源,可以删除资源或资源组。 删除资源组同时也会删除与之相关联的任何其他资源。

示例代码

另请参阅

先决条件

设置

检索密钥和终结点

若要成功地对 Azure OpenAI 发出调用,需要准备好以下各项:

变量名称
ENDPOINT 从 Azure 门户检查资源时,可在“密钥和终结点”部分中找到此值。 也可在“Azure OpenAI Studio”>“操场”>“代码视图”中找到该值。 示例终结点为:https://docs-test-001.openai.azure.com/
API-KEY 从 Azure 门户检查资源时,可在“密钥和终结点”部分中找到此值。 可以使用 KEY1KEY2
DEPLOYMENT-NAME 此值将对应于在部署模型时为部署选择的自定义名称。 此值可在 Azure 门户中的“资源管理”>“部署”下,或者在 Azure OpenAI Studio 中的“管理”>“部署”下找到此值。

在 Azure 门户中转到你的资源。 可以在“资源管理”部分找到“终结点和密钥”。 复制终结点和访问密钥,因为在对 API 调用进行身份验证时需要这两项。 可以使用 KEY1KEY2。 始终准备好两个密钥可以安全地轮换和重新生成密钥,而不会导致服务中断。

Azure 门户中 Azure OpenAI 资源概述边栏选项卡的屏幕截图,其中终结点和访问密钥的位置用红圈标示。

为密钥和终结点创建和分配持久环境变量。

环境变量

为密钥和终结点创建和分配持久环境变量。

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE" 

REST API

创建助手

注意

使用 Azure OpenAI 时,model 参数需要模型部署名称。 如果模型部署名称与基础模型名称不同,则需要将代码调整为 "model": "{your-custom-model-deployment-name}"

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "You are an AI assistant that can write code to help answer math questions.",
    "name": "Math Assist",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-1106-preview"
  }'

工具

单个助手最多可以访问 128 个工具,包括code interpreter 和通过函数创建的任何自定义工具。

创建线程

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d ''

将用户问题添加到线程

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
      "role": "user",
      "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
    }'

运行线程

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/runs \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

检索运行状态

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/runs/run_abc123 \
  -H "api-key: $AZURE_OPENAI_API_KEY" \

助手响应

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \

理解结果

在此示例中,我们将创建一个启用了代码解释器的助手。 当我们向助手提出数学问题时,它会将问题转换为 python 代码,并在沙盒环境中执行代码,以确定问题的答案。 由模型创建并进行测试以得出答案的代码为:

    from sympy import symbols, Eq, solve  
      
    # Define the variable  
    x = symbols('x')  
      
    # Define the equation  
    equation = Eq(3*x + 11, 14)  
      
    # Solve the equation  
    solution = solve(equation, x)  
    solution  

请务必记住,虽然代码解释器支持模型通过将问题转换为代码并在 Python 沙盒中以迭代方式运行该代码来响应更复杂的查询,直到它得出答案,但仍需对响应进行验证,以确认模型是否已正确地将问题转换为代码中的有效表示形式。

清理资源

如果你想要清理和删除 OpenAI 资源,可以删除资源或资源组。 删除资源组同时也会删除与之相关联的任何其他资源。

另请参阅