分享方式：

助理 API (預覽) 訊息參考

  • 文章

注意

  • 檔案搜尋可以內嵌每個助理最多 10,000 個檔案 - 比之前多 500 倍。 其速度很快，可透過多對話搜尋支援平行查詢，以及增強重新排名和查詢重寫的功能。
    • 向量存放區是 API 中的新物件。 一旦檔案新增至向量存放區，它就會自動進行剖析、區塊化和內嵌，並準備好提供搜尋。 向量存放區可以跨助理和對話使用，簡化檔案管理和計費。
  • 我們已新增 tool_choice 參數的支援，可用來強制在特定執行中使用特定工具 (例如檔案搜尋、程式碼解譯器或函式)。

本文提供新助理 API (預覽) 的 Python 和 REST 參考文件。 入門指南會提供更深入的逐步指引。

建立訊息

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages?api-version=2024-08-01-preview

建立訊息。

路徑參數

參數 類型​ 必要 描述
thread_id string 必要 要為其建立訊息的對話識別碼。

要求本文

名稱 類型​​ 必要 描述
role string 必要 正在建立訊息的實體角色。 可以是 user 或 assistant。 user 表示訊息由實際使用者所傳送，且多數情況下應用來代表使用者產生的訊息。 assistant 表示訊息由助理所產生。 使用此值，將來自助理的訊息插入對話中。
content 字串 必要 訊息的內容。
attachments 陣列 選擇性 附加至訊息的檔案清單，以及應新增檔案的工具。
metadata map 選擇性 可附加至物件的索引鍵/值組 (16 個為一組)。 這有助於以結構化格式儲存物件的其他相關資訊。 索引鍵的長度上限為 64 個字元，而值的長度上限為 512 個字元。

傳回

訊息物件。

建立訊息要求範例

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

thread_message = client.beta.threads.messages.create(
  "thread_abc123",
  role="user",
  content="How does AI work? Explain it in simple terms.",
)
print(thread_message)

列出訊息

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages?api-version=2024-08-01-preview

傳回給定執行緒的訊息清單。

路徑參數

參數 類型​ 必要 描述
thread_id string 必要 訊息所屬對話的識別碼。

查詢參數

名稱 類型​​ 必要 描述
limit 整數 (選擇性) 預設值為 20 要傳回的物件數目限制。 限制的範圍可以介於 1 到 100 之間，預設值為 20。
order 字串 (選擇性) 預設值為 desc 依物件的 created_at 時間戳記排序次序。 asc 代表遞增排序，而 desc 代表遞減排序。
after 字串 選擇性 用於分頁的游標。 after 是在清單中定義您的位置的物件識別碼。 例如，如果您提出清單要求並收到 100 個物件 (結尾為 obj_foo)，則後續呼叫可以包含 after=obj_foo 來擷取清單的下一頁。
run_id 字串 選用 依產生訊息的執行識別碼來篩選訊息。
before 字串 選擇性 用於分頁的游標。 before 是在清單中定義您的位置的物件識別碼。 例如，如果您提出清單要求並收到 100 個物件 (結尾為 obj_foo)，則後續呼叫可以包含 before=obj_foo 來擷取清單的上一頁。

傳回

訊息物件清單。

清單訊息要求範例

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

thread_messages = client.beta.threads.messages.list("thread_abc123")
print(thread_messages.data)

擷取訊息

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-08-01-preview

擷取訊息檔案。

路徑參數

參數 類型​ 必要 描述
thread_id string 必要 訊息所屬對話的識別碼。
message_id 字串 必要 要擷取之訊息的識別碼。

傳回

符合指定識別碼的訊息物件。

擷取訊息要求範例

from openai import AzureOpenAI

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

message = client.beta.threads.messages.retrieve(
  message_id="msg_abc123",
  thread_id="thread_abc123",
)
print(message)

修改訊息

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-08-01-preview

修改訊息。

路徑參數

參數 類型​ 必要 描述
thread_id string 必要 訊息所屬對話的識別碼。
message_id 字串 必要 要修改之訊息的識別碼。

要求本文

參數 類型​ 必要 描述
metadata map 選擇性 可附加至物件的索引鍵/值組 (16 個為一組)。 這有助於以結構化格式儲存物件的其他相關資訊。 索引鍵的長度上限為 64 個字元，而值的長度上限為 512 個字元。

傳回

修改過的訊息物件。

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

message = client.beta.threads.messages.update(
  message_id="msg_abc12",
  thread_id="thread_abc123",
  metadata={
    "modified": "true",
    "user": "abc123",
  },
)
print(message)

刪除訊息

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-08-01-preview

刪除訊息。

路徑參數

參數 類型​ 必要 描述
thread_id string 必要 訊息所屬對話的識別碼。
message_id 字串 必要 要修改之訊息的識別碼。

傳回

訊息物件的刪除狀態。

from openai import AzureOpenAI
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

deleted_message = client.beta.threads.messages.delete(
  message_id="msg_abc12",
  thread_id="thread_abc123",
)
print(deleted_message)

訊息物件

代表執行緒內的訊息。

名稱 類型​​ 描述
id 字串 識別碼，可在 API 端點中參考。
object 字串 物件類型，一律為 thread.message。
created_at 整數 訊息建立時的 Unix 時間戳記 (以秒為單位)。
thread_id 字串 此訊息所屬的執行緒識別碼。
role 字串 產生訊息的實體。 user 或 assistant 的其中之一。
content 陣列 文字和/或影像陣列中的訊息內容。
assistant_id string 或 null 撰寫此訊息的助理識別碼 (如果適用)。
run_id string 或 null 與此訊息的撰寫相關聯的執行識別碼 (如果適用)。
file_ids 陣列 助理應該使用的檔案識別碼清單。 適用於可存取檔案的工具，例如擷取和 code_interpreter。 最多可以將 10 個檔案附加至訊息。
metadata map 可附加至物件的索引鍵/值組 (16 個為一組)。 這有助於以結構化格式儲存物件的其他相關資訊。 索引鍵的長度上限為 64 個字元，而值的長度上限為 512 個字元。