共用方式為

小幫手 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-05-01-preview

建立訊息。

路徑參數

參數 類型​ 必要 描述
thread_id 字串 必要 要為其建立訊息之線程的標識碼。

要求本文

名稱 類型​​ 必要 描述
role 字串 必要 正在建立訊息之實體的角色。 可以是 user 或 assistant。 assistant 表示訊息是由實際用戶傳送，而且應該在大部分情況下用來代表用戶產生的訊息。 assistant 表示小幫手會產生訊息。 使用這個值，將小幫手的訊息插入交談中。
content 字串 必要 訊息的內容。
file_ids 陣列 選擇性 訊息應該使用的檔案識別碼清單。 最多可以有10個檔案附加至訊息。 適用於可存取和使用檔案之擷取和code_interpreter等工具。
metadata map 選擇性 可附加至物件的16個索引鍵/值組集合。 這對於以結構化格式儲存物件的其他資訊很有用。 索引鍵長度上限為 64 個字元，且值長度上限為 512 個字元。

傳回

訊息物件。

建立訊息要求的範例

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")
    )

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-05-01-preview

傳回指定線程的訊息清單。

路徑參數

參數 類型​ 必要 描述
thread_id 字串 必要 訊息所屬線程的標識碼。

查詢參數

名稱 類型​​ 必要 描述
limit 整數 選擇性 - 預設值為 20 要傳回之對象的數目限制。 限制的範圍可以介於 1 到 100 之間，預設值為 20。
order 字串 選擇性 - 預設值為 desc 依物件的created_at時間戳排序順序。 遞增順序的 asc 和遞減順序的 desc。
after 字串 選擇性 用於分頁的數據指標。 after 是定義清單中位置的物件標識碼。 例如，如果您提出清單要求並接收 100 個對象，結尾為 obj_foo，則後續呼叫可以包含 after=obj_foo，以擷取清單的下一頁。
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-05-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}/files?api-version=2024-05-01-preview

傳回訊息檔案的清單。

參數 類型​ 必要 描述
thread_id 字串 必要 訊息和檔案所屬線程的標識碼。
message_id 字串 必要 檔案所屬之訊息的標識碼。

查詢參數

名稱 類型​​ 必要 描述
limit 整數 選擇性 - 預設值為 20 要傳回之對象的數目限制。 限制的範圍可以介於 1 到 100 之間，預設值為 20。
order 字串 選擇性 - 預設值為 desc 依物件的created_at時間戳排序順序。 遞增順序的 asc 和遞減順序的 desc。
after 字串 選擇性 用於分頁的數據指標。 after 是定義清單中位置的物件標識碼。 例如，如果您提出清單要求並接收 100 個對象，結尾為 obj_foo，則後續呼叫可以包含 after=obj_foo，以擷取清單的下一頁。
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-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

message_files = client.beta.threads.messages.files.list(
  thread_id="thread_abc123",
  message_id="msg_abc123"
)
print(message_files)

擷取

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

擷取訊息檔案。

路徑參數

參數 類型​ 必要 描述
thread_id 字串 必要 訊息所屬線程的標識碼。
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)

擷取訊息檔案

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

擷取訊息檔案。

路徑參數

參數 類型​ 必要 描述
thread_id 字串 必要 訊息和檔案所屬線程的標識碼。
message_id 字串 必要 檔案所屬之訊息的標識碼。
file_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_files = client.beta.threads.messages.files.retrieve(
    thread_id="thread_abc123",
    message_id="msg_abc123",
    file_id="assistant-abc123"
)
print(message_files)

修改訊息

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

修改訊息。

路徑參數

參數 類型​ 必要 描述
thread_id 字串 必要 訊息所屬線程的標識碼。
message_id 字串 必要 要修改之訊息的標識碼。

要求本文

參數 類型​ 必要 描述
中繼資料 map 選擇性 可附加至物件的16個索引鍵/值組集合。 這對於以結構化格式儲存物件的其他資訊很有用。 索引鍵長度上限為 64 個字元，且值長度上限為 512 個字元。

傳回

修改過的 訊息 物件。

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.update(
  message_id="msg_abc12",
  thread_id="thread_abc123",
  metadata={
    "modified": "true",
    "user": "abc123",
  },
)
print(message)

Message 物件

表示線程內的訊息。

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

訊息檔案物件

附加至訊息的檔案清單。

名稱 類型​​ 描述
id 字串 標識碼，可在 API 端點中參考。
object 字串 物件類型，一律為 thread.message.file。
created_at 整數 建立訊息檔案時的 Unix 時間戳（以秒為單位）。
message_id 字串 附加檔案之訊息的標識碼。