如何使用提示流程 SDK 追蹤您的應用程式 | Azure AI Studio
重要
本文所述的部分功能可能僅適用於預覽版。 此預覽版本沒有服務等級協定，不建議將其用於生產工作負載。 可能不支援特定功能，或可能已經限制功能。 如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。
追蹤是功能強大的工具，可讓開發人員深入了解生成式 AI 應用程式的執行流程，例如代理程式、AutoGen，以及檢索增強世代 (RAG) 使用案例。 追蹤提供執行流程的詳細檢視，包括應用程式內每個節點的輸入和輸出。 這項基本資訊在偵錯複雜應用程式或最佳化效能時證明相當重要。
更多的開發人員會使用各種架構，例如 Langchain、Semantic Kernel、OpenAI 和各種類型的代理程式以建立 LLM 型應用程式。 使用提示流程 SDK 進行追蹤時，這會為 LLM 型應用程式增強可見度和簡化疑難排解，以有效支援開發、反覆項目和生產監視。 在 AI Studio 追蹤時，這會遵循 OpenTelemetry 規格，擷取和視覺化任何 AI 應用程式的內部執行詳細資料，增強整體開發體驗。
企業級雲端平台上進行 AI Studio 追蹤的優點
此外，我們現在在 AI Studio 上提供持續性的本機測試，這是企業級雲端平台，可大幅增強共同作業、持續性和測試歷程記錄管理。
透過追蹤，您可以：
- 擁有雲端式位置，可保存及追蹤您的歷史測試。
- 輕鬆擷取和視覺化測試結果，並比較不同測試案例的輸出。
- 重複使用您先前的測試資產以供日後使用，例如人類意見反應、資料策展等。
- 促進未來資源使用率提高。
- 輕鬆偵錯並最佳化您的應用程式。 若要開始偵錯 LLM 應用程式案例，請參閱使用 LLM 應用程式進行追蹤
- 於 RAG 應用程式中分析檢索和產生程序。
- 觀察多代理程式案例中的多代理程式互動。 若要在多代理程式案例中開始使用追蹤，請參閱使用 AutoGen 追蹤。
記錄和檢視應用程式的追蹤
Azure Studio 提供記錄和管理 LLM 應用程式測試和評估的追蹤功能，同時透過向下切入追蹤檢視以進行偵錯和觀察。
追蹤現今的任何應用程式功能都會在提示流程開放原始碼套件中實作，讓使用者追蹤 LLM 呼叫或函式，以及 LangChain 和 AutoGen 等 LLM 架構，無論您使用哪一個架構，都遵循 OpenTelemetry 規格。
在應用程式啟用追蹤
程式碼優先 - 請確定您已在提示流程中為追蹤標註程式碼！
- 安裝提示流程：需要 promptflow-tracing
- 檢測您的應用程式程式碼：使用
@trace和start_trace()。 - 在本機中測試和檢視追蹤
如需提示流程中追蹤的詳細資料，請參閱此提示流程文件。
將追蹤記錄至 AI Studio
設定追蹤目的地
根據預設，追蹤會記錄並檢視在您的本機環境中。 若要在雲端版中記錄 AI Studio，您需要將 trace destination 設為指定 AI Studio 專案。
您可以參考下列步驟，將追蹤目的地設定為 AI Studio 專案。
首先，請確定已安裝並登入 Azure CLI：
az login
接下來，執行下列命令來設定追蹤目的地。 以您的特定訂用帳戶 ID、資源群組名稱和 AI Studio 專案名稱取代 <your_subscription_id>、<your_resourcegroup_name> 和 <your_studio_project_name>：
pf config set trace.destination=azureml://subscriptions/<your_subscription_id>/resourcegroups/<your_resourcegroup_name>/providers/Microsoft.MachineLearningServices/workspaces/<your_studio_project_name>
注意
美國西部 3 （westus3） 區域不支持追蹤。
集合
集合是相關聯的追蹤群組。 在 AI Studio 中，這些集合及其內部追蹤會管理並儲存在 [集合] 索引標籤下的追蹤模組中。
移至您在 AI Studio 中的專案。
從左側窗格中，選取 [追蹤]。 您會看到 [集合] 索引標籤。您在集合清單中只能看到自己的集合。 在此範例中，還沒有任何集合。
[集合] 索引標籤會顯示您所建立所有集合的完整清單。 這會顯示每個集合的基本中繼資料，包括其名稱、執行位置、上次更新時間和建立時間。
- 執行位置：表示應用程式是在本機還是雲端中執行。 雲端集合會與特定的提示流程雲端製作測試歷程記錄和產生的追蹤相關聯。 在這個案例，集合名稱與提示流程顯示名稱相同。
- 更新日期：顯示最近一次記錄到集合的新追蹤。 根據預設，集合會根據其更新時間以遞減順序排序。
- 建立日期：最初建立集合的時間。
選取集合的名稱，即可存取該集合內所有追蹤的清單。 只有一部分的追蹤可以與其他人共用。 如需詳細資訊，請參閱共用追蹤。
記錄追蹤時，您可以選擇指定集合名稱，將它與其他相關追蹤分組在一起。 您可以建立多個集合，以更妥善地組織追蹤。 如果記錄追蹤時未指定集合名稱，則預設為專案資料夾名稱或預設集合。
自訂集合
若要更妥善地組織追蹤，您可以在記錄追蹤時指定自訂集合名稱。
如果您要追蹤自己的應用程式，您可以在程式碼的 start_trace() 函式中設定集合名稱：
from promptflow.tracing import start_trace, trace
@trace
def my_function(input: str) -> str:
output = input + "Hello World!"
return output
my_function("This is my function")
start_trace(collection="my_custom_collection")
檢視追蹤
首先，您必須完成先前的步驟，才能在雲端中檢視追蹤：
現在，直接執行 Python 指令碼。 成功執行時，輸出會顯示雲端追蹤連結。 其看起來會像這樣：
Starting prompt flow service...
...
You can view the traces in cloud from AI Studio: https://ai.azure.com/projecttrace/detail/....
選取 URL 即可瀏覽至雲端入口網站上的追蹤詳細資料頁面。 此頁面與本機追蹤檢視類似。
追蹤詳細資料檢視提供應用程式內作業的完整結構化概觀。
了解追蹤詳細資料檢視
在追蹤檢視右上角，您可以找到以下項目：
- 追蹤名稱：這與根範圍名稱相同，代表應用程式的輸入函式名稱。
- 狀態：這可能是「已完成」或「失敗」。
- 持續時間總計：這是測試執行的持續時間總計。 將滑鼠停留在上方以檢視開始和結束時間。
- 權杖總計：這是測試的權杖成本總計。 將滑鼠停留在上方即可檢視提示權杖和已完成的權杖。
- 建立時間：建立追蹤的時間。
在左側，您可以看到階層式樹狀結構。 此結構會顯示函式呼叫的順序。 每個函式呼叫的中繼資料都會組成範圍。 這些範圍會連結在類似樹狀的結構中，可說明執行順序。
在提示流程 SDK 中，我們定義幾個範圍類型，包括 LLM、函式、內嵌、擷取和流程。 系統會自動在指定的屬性和事件中使用執行資訊來建立範圍。
每個範圍都可讓您檢視：
- 函式名稱：根據預設，這是程式碼中所定義的函式名稱。 然而，這也可以是透過 Open Telemetry 定義的自訂範圍名稱。
- 持續時間：這代表函式執行的持續時間。 將滑鼠停留在上方以檢視開始和結束時間。
- LLM 呼叫權杖：這是 LLM 呼叫的權杖成本。 將滑鼠停留在上方即可檢視提示權杖和已完成的權杖。
藉由選取特定範圍，您可以移至右側檢視相關聯的詳細資訊。 這項資訊包括輸入、輸出、原始 JSON、記錄，以及例外狀況，這對於觀察和偵錯您的應用程式極為重要。
針對 LLM 範圍，這會提供清晰的對話檢視。 這包括系統提示、使用者提示，以及助理回應。 這項資訊在多代理程式案例特別重要，因為這可讓您了解對話的流程，以及 LLM 中繼自動呼叫內的互動。
您可以選取 [原始 JSON] 索引標籤，以檢視範圍的 JSON 資料。 在偵錯和疑難排解方面，此格式可能更適合開發人員。
共用追蹤
若您想要與具有專案權限的其他人共用追蹤，您可以選取追蹤詳細資料頁面右上角的 [共用] 按鈕，即可取得複製以與其他人共用的頁面連結。
注意
共用追蹤是唯讀，只有擁有專案權限的人員可以透過連結來予以檢視。
相關內容
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應