深入解析 Azure OpenAI Assistants API

简介

最近，我深入研究了 OpenAI 助手 API。2024 年 2 月，微软在公众预览中发布了他们的助手 API。该 API 的工作方式与 OpenAI 助手 API 类似，同时可以与部署在您选择区域的 Azure（微软云平台）OpenAI 模型结合使用。

助理 API 的目标是帮助开发者更轻松地创建具有类似副驾驶体验的应用程序。通过该 API，开发者可以更方便地为助手提供额外的知识，或通过调用外部 API，让助手与外部世界交互。

如果您曾使用 Azure OpenAI 的聊天完成 API 创建过基于聊天的副驾驶应用，您可能知道该 API 是无状态的，不会记录对话历史。作为开发者，您需要手动维护和管理会话历史记录，并将其传递给完成 API。而助理 API 是有状态的，它通过线程自动管理对话历史记录，无需您手动管理对话状态，也无需担心超出模型的上下文窗口限制。

除了线程管理，助理 API 还支持工具功能。其中一个工具是 代码解释器，它是一个沙盒式的 Python 环境，可以帮助解决复杂问题。如果您是 ChatGPT Plus 用户，可能已经熟悉该工具。代码解释器通常用于解决数学问题，但它的功能并不限于此。此外，您还可以定义自定义函数，例如通过调用 API 查询数据库并将结果返回给助手。

在深入代码示例之前，我们需要了解以下组件：

• 助手：基于 Azure OpenAI 模型自定义的 AI，可以访问文件和工具。
• 话题：助手与用户之间的对话。
• 消息：由助手或用户创建的消息，可以是文本、图像或文件，消息存储在线程中。
• 运行：通过运行线程从模型中获取响应，例如，用户在线程中提出问题后运行线程，模型可以返回文本响应或执行工具调用。
• 运行步骤：助手在运行过程中采取的详细步骤，例如调用工具。

接下来，我们通过代码示例进一步了解如何使用这些功能。完整代码可在 GitHub 上找到：Azure Assistants API 示例。

初始化 OpenAI 客户端并创建助手

我们将使用 .env 文件加载 Azure OpenAI 的 API 密钥、端点和 API 版本。需要确保您在支持的地区（例如瑞典中部）使用 Azure OpenAI 资源，并将 API 版本设置为 2024-02-15-preview。

import os
from dotenv import load_dotenv
from openai import AzureOpenAI

load_dotenv()

# 创建 Azure OpenAI 客户端
client = AzureOpenAI(
    api_key=os.getenv('AZURE_OPENAI_API_KEY'),
    azure_endpoint=os.getenv('AZURE_OPENAI_ENDPOINT'),
    api_version=os.getenv('AZURE_OPENAI_API_VERSION')
)

# 创建助手
assistant = client.beta.assistants.create(
    name="Math Tutor",
    instructions="""You are a math tutor that helps users solve math problems.
    You have access to a sandboxed environment for writing and testing code.
    Explain to the user why you used the code and how it works
    """,
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-preview"
)

上述代码通过 client.beta.assistants.create 方法创建了一个助手。需要注意，OpenAI 助手目前仍处于测试阶段，因此 OpenAI 库中也反映了这一点。

在创建助手时，我们为其指定了具体的指令和工具。在本例中，我们使用了内置的代码解释器工具，用于解决数学问题并生成图表。需要确保所选模型已在您的区域中部署，例如本文使用的是 gpt-4-turbo 预览版。

创建的助手会显示在 Azure OpenAI 助手 Playground 中。例如，我通过运行相同的代码多次创建了一个 Math Assistant：

在 Playground 中，您可以直接与助手进行交互。例如，我请求助手绘制正弦波：

助手会根据指令解释绘图过程，并最终生成图像文件，该文件会显示在 Playground 中。此外，右侧面板提供了 API 指令，您可以点击这些指令执行操作并查看 JSON 响应。

需要注意的是，您可以通过助手的 ID 重用已创建的助手，也可以直接在 Azure 门户中创建助手，而无需通过代码实现。

创建线程并添加消息

以下代码展示了如何创建线程并向其中添加消息。创建线程后会生成一个线程 ID，随后可以向线程中添加用户消息。

# 创建线程
thread = client.beta.threads.create()

# 打印线程 ID
print("Thread id: ", thread.id)

# 添加用户消息
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="Solve the equation y = x^2 + 3 for x = 3 and plot the function graph."
)

# 显示线程中的消息
thread_messages = client.beta.threads.messages.list(thread.id)
print(thread_messages.model_dump_json(indent=2))

在上述代码中，message 包含了用户的第一个问题。消息的 JSON 数据结构如下：

"content": [
    {
        "text": {
            "annotations": [],
            "value": "Solve the equation y = x^2 + 3 for x = 3 and plot the function graph."
        },
        "type": "text"
    }
]

运行线程

添加消息后，我们需要运行线程以获取助手的响应。

run = client.beta.threads.runs.create(
  thread_id=thread.id,
  assistant_id=assistant.id
)

status = run.status

while status not in ["completed", "cancelled", "expired", "failed"]:
    time.sleep(2)
    run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id)
    status = run.status
    print(f'Status: {status}')
    clear_output(wait=True)

print(f'Status: {status}')

运行线程时，助手会根据线程 ID 和助手 ID 返回响应。需要注意，运行状态需要手动检查，只有在状态为 completed 时，运行才算成功。

解析运行后的消息

运行完成后，我们可以解析助手的响应。以下代码展示了如何处理助手返回的消息：

messages = client.beta.threads.messages.list(
    thread_id=thread.id
)

messages_json = json.loads(messages.model_dump_json())

for item in reversed(messages_json['data']):
    for content in reversed(item['content']):
        if 'text' in content:
            display(Markdown(content['text']['value']))
        if 'image_file' in content:
            file_id = content['image_file']['file_id']
            file_content = client.files.content(file_id)
            img = Image.open(file_content)
            img = img.resize((400, 400))
            display(img)

上述代码会检查消息内容是否包含文本或图像，并分别以 Markdown 或图像形式显示。

后续问题

助理 API 的一个优势在于无需维护聊天历史记录。只需将后续问题添加到线程中并再次运行即可。例如，添加问题 "Is this a concave function?" 后，助手会返回以下响应：

需要注意的是，目前（2024 年 2 月），助理 API 会尝试将所有消息放入模型的上下文窗口中。如果上下文窗口较大，长对话可能会消耗大量 Token。未来，OpenAI 和微软计划引入以下功能：

• 控制 Token 数量（例如，将 Token 限制为 2000，即使模型允许 8000）。
• 生成消息摘要，并在运行线程时将摘要作为上下文传递。

总结

Azure OpenAI 的助理 API 让开发者能够更轻松地创建支持工具（如代码解释器）或自定义函数的助手。本篇文章主要介绍了如何使用代码解释器工具的基础操作。

在后续文章中，我们将探讨自定义函数以及如何处理上传文件。

请注意，该功能目前仍处于公众预览阶段，不建议在生产环境中使用。

原文链接: https://blog.baeke.info/2024/02/08/a-look-at-the-azure-openai-assistants-api/