本頁面說明如何透過系統指令編寫有效的提示詞,以及為部分資料來源提供額外的結構化情境,以最佳方式為對話式數據分析 API 資料代理提供編寫的情境。雖然提供作者背景資訊為選用步驟,但結構良好的作者背景資訊可提升 API 回覆的準確度和關聯性。
什麼是編寫的背景資訊?
開發人員可提供編寫的背景資訊,引導資料代理的行為,並調整 API 的回覆。這類指引包括任意形式的系統指令,以及某些資料來源的結構化內容欄位,其中包含資料表說明和查詢範例等資訊。為了回答問題,代理會將這項編寫的背景資訊與資料來源 (例如 BigQuery 資料表、Looker 探索、數據分析和資料庫資料來源) 的資訊,以及對話記錄 (適用於多輪對話) 結合。
透過結構化情境欄位和任意形式的系統指令,提供明確指引,提升代理理解使用者問題的能力,並生成實用準確的回覆。如果連結至 BigQuery 資料表等資料,明確定義情境就特別實用。舉例來說,您可以使用自訂背景資訊,為代理提供下列類型的指引:
- 特定業務邏輯:將「忠實」顧客定義為在特定時間範圍內消費超過五次的顧客。
- 回覆格式:將資料代理的所有回覆摘要成 20 字以內,節省使用者時間。
- 資料呈現:將所有數字格式調整為符合公司樣式指南。
提供背景資訊
可提供的具體資訊取決於資料來源。如果是 BigQuery 資料、Looker 資料和資料庫資料,您可以定義結構化脈絡和系統指令。為獲得最佳結果,請先透過可用的結構化欄位,向代理提供背景資訊。接著,您可以定義系統指令,提供額外指引。
您可以在 API 欄位中提供結構化背景資訊,例如資料表說明和查詢範例。您可以使用 system_instruction 參數,以 YAML 格式的字串提供系統指令。
定義自訂情境後,您可以透過下列任一呼叫,將其提供給 API:
- 建立永久資料代理:在要求主體的
published_context物件中加入編寫的脈絡,設定代理在多個對話中持續執行的行為。詳情請參閱「建立資料代理」(HTTP) 或「設定有狀態或無狀態對話的背景資訊」(Python SDK)。 - 傳送無狀態要求:在對話要求的
inline_context物件中提供編寫的脈絡,定義代理在該特定 API 呼叫中的行為。詳情請參閱「建立無狀態多輪對話」(HTTP) 或「使用 API 提問」(Python SDK)。 - 傳送查詢資料要求:如果是資料庫資料來源,請在查詢資料要求的
agent_context_reference物件中,提供已建立內容集的 ID。詳情請參閱「定義資料庫資料來源的資料代理背景資訊」。
建構代理的最佳做法:對編寫的內容使用版本管控機制
使用 Conversational Analytics API 建構代理時,請使用 stagingContext、publishedContext 和 lastPublishedContext 欄位控管情境版本。以下用途說明如何使用這些欄位,建立代理內容的測試版和正式版。
假設您使用含有 publishedContext 欄位的現有代理,但需要更新代理 (例如將所有圖表從藍色改為綠色)。
如要進行變更並在發布前測試,請按照下列步驟操作:
- 在「
stagingContext」欄位中變更代理,然後測試變更後的代理。 - 變更完成後,請使用
stagingContext的變更更新publishedContext欄位。 - 您可以視需要將
publishedContext更新為lastPublishedContext,還原為舊版代理程式。