管理推論掛鉤

設定 Inference hooks

Copy page



為您的 Claude Enterprise 組織允許 Inference hooks、連接您的 AI 安全伺服器，並控制強制執行、失敗處理與逐步推出。

Inference hooks（推論掛鉤）會將您組織的提示傳送至您選擇的 AI 安全伺服器，並在 Claude 處理每個請求之前，先等待允許或拒絕的裁決（verdict）。本頁將逐步說明如何開啟此功能、連接您的伺服器，以及控制強制執行。若要了解 Inference hooks 是什麼以及何時使用，請參閱 Inference hooks 概覽。若要建置 AI 安全伺服器本身，請參閱開發 Inference hooks 整合。

開始之前

您需要：

• claude.ai 中的 organization:manage 權限，只有 Owner 和 Primary owner 角色擁有此權限。Admin 角色沒有此權限。
• 一個接受判定請求的 AI 安全伺服器 HTTPS 端點：使用連接埠 443 的 https:// URL，位於可公開路由的主機上，且無需重新導向即可連線。不支援反向通道主機（ngrok 及類似的通道服務）：Anthropic 的網路政策會封鎖它們。請勿透過通道進行測試；請將您的伺服器託管在您控制的網域上。如需完整的託管需求，以及建置伺服器和驗證已簽署請求的方式，請參閱開發 Inference hooks 整合。

設定 Inference hooks

共有三種強制執行狀態：關閉（Enforce verdicts 為關閉：永遠不會聯繫您的 AI 安全伺服器，且不會檢查提示）、影子（Enforce verdicts 為開啟且 Mode 設為 Shadow mode：您的 AI 安全伺服器會收到提示並回傳裁決，但不會封鎖任何內容），以及強制執行中（Enforce verdicts 為開啟且 Mode 設為 Allow the request 或 Block the request：拒絕裁決會封鎖該請求）。以下步驟會將一個新設定從關閉帶到強制執行中。

1. 1

   為您的組織允許 Inference hooks

   前往 claude.ai > Organization settings > Data and privacy，找到 Inference hooks 區段。開啟 Allow for your organization。

   開啟此選項會解鎖 Inference hooks 設定頁面，並一律強制將 Enforce verdicts 設為關閉，因此允許此功能本身絕不會啟動檢查：即使是先前已開啟強制執行的設定，在您於最後一個步驟重新開啟 Enforce verdicts 之前，仍會維持不檢查的狀態。

2. 2

   開啟 Inference hooks 設定頁面

   仍在 Data and privacy 中，開啟 Inference hooks 區段以進入 Inference hooks 設定頁面。它位於 Data and privacy 之下，而非設定導覽列中的獨立項目，因此其麵包屑導覽顯示為 Data and privacy / Inference hooks。在您儲存端點之前，頁面會警告提示尚未受到檢查，且 Enforce verdicts 會維持關閉並顯示 Requires endpoint 標記。

3. 3

   設定您的端點

   按一下 Configure 以開啟 Set up endpoint 對話方塊，並輸入 Endpoint URL：接收判定請求的 https:// URL。僅接受 https:// URL。

   此時對話方塊不會要求其他資訊：自訂請求標頭在步驟 5 設定，失敗處理則在步驟 6 設定。按一下 Next 以儲存。儲存端點後，按鈕會顯示為 Edit。

4. 4

   儲存您的簽署密鑰

   第一次儲存時會產生您的 webhook「signing secret」（簽署密鑰），並僅顯示一次。在按一下 Next 之前，請複製並安全地儲存它：此密鑰之後無法再取得，只能輪替。

   您的 AI 安全伺服器會使用此密鑰來驗證其收到的每個請求上的簽章，包括下一個步驟中的連線測試。如需驗證程序，請參閱驗證簽章。

5. 5

   新增請求標頭並測試連線

   在簽署密鑰對話方塊上按一下 Next 會重新開啟端點對話方塊，此時會多出兩個控制項：

   • Custom request headers： 最多 16 個靜態標頭，會隨每個判定請求一起傳送，讓您的 AI 安全伺服器能夠驗證呼叫者。標頭值會以加密方式儲存，且不會再次顯示；儲存後只會顯示標頭名稱。由於這些值為唯寫，儲存對標頭的任何變更都需要重新輸入每個值。變更端點 URL 會清除所有已儲存的標頭值，以確保您的憑證永遠不會被傳送到新的目的地；變更 URL 後請重新輸入這些值。標頭名稱必須使用標準 HTTP token 字元，並使用 - 而非 _，且不得與保留名稱衝突（請求框架標頭，例如 Content-* 和 Host；代理與 cookie 標頭；用戶端位址標頭，例如 X-Forwarded-*；webhook-* 簽章標頭；以及 X-Anthropic-* 前綴）。值必須是可列印的 ASCII 字元。
   • Test connection： Claude 會將一個合成的測試提示傳送到表單中目前填寫的 URL 和標頭，而非已儲存的值，因此請在測試前重新輸入任何已儲存的標頭值。成功時，結果會回報您的 AI 安全伺服器針對測試提示回傳的是允許還是拒絕判定，這能讓您在開始強制執行之前發現「全部拒絕」的預設行為。

   按一下 Save 以儲存您輸入的任何標頭。

   常見的失敗結果：

   結果	檢查事項
   URL 遭拒	URL 未通過結構檢查。請使用連接埠 443 的 https:// URL。
   私人或內部 IP	URL 的主機是私人或內部 IP 位址、IPv6 位址或 localhost。請使用可公開路由的主機。
   逾時	AI 安全伺服器未在逾時時間內回傳判定。
   傳輸錯誤	DNS 解析、TLS 交握或連線失敗，或主機名稱解析為私人位址。
   非 200 狀態	AI 安全伺服器回應的狀態碼不是 200。判定必須以 HTTP 200 回傳；不會跟隨重新導向，且重新導向會被視為失敗。
   無法解析的回應	AI 安全伺服器有回應，但內容不是有效的判定。
   需要簽署密鑰	您的組織沒有簽署密鑰，因此測試會以未簽署的方式傳送。請按一下 Request signing 下的 Generate secret，然後再次測試。

6. 6

   選擇失敗處理方式與逾時

   在 Failure handling 下，設定 Mode 以選擇當 AI 安全伺服器無法連線或裁決逾時時的處理方式：

   • Block the request：當您的 AI 安全伺服器無法提供裁決時停止推論（失敗即關閉，fail closed）。
   • Allow the request：讓請求在未經檢查的情況下繼續送往模型（失敗即開放，fail open）。

   下拉選單的第三個選項 Shadow mode 是一種逐步推出工具，而非失敗政策；請參閱影子模式。

   接著設定 Prompt verdict timeout (ms)：1 至 10,000 毫秒，預設為 5,000 毫秒。此預算涵蓋整個交換過程，較慢的裁決會被視為伺服器無法連線，因此請設定您的伺服器能夠穩定達成的最低值。

   此區段中的變更會在您進行時即時儲存。首次儲存時，預設值為 Allow the request 與 5,000 毫秒。

7. 7

   選擇逐步推出百分比

   在 Rollout 下，設定 Requests inspected (%)，以便在您讓 AI 安全伺服器上線的過程中，對一定百分比的請求執行檢查。此值範圍為 0 至 100：100 表示檢查所有請求，0 則關閉檢查。

   每個請求會針對其整個對話輪次擲骰一次，因此單一對話可能在不同輪次間被部分檢查。落在取樣百分比之外的請求會在未經檢查的情況下繼續進行，即使失敗處理設為 Block the request 亦然。

8. 8

   開啟 Enforce verdicts

   若要先針對即時流量評估裁決而不封鎖任何人，請在開啟強制執行之前將 Mode 設為 Shadow mode（步驟 6）；請參閱影子模式。

   開啟 Enforce verdicts，讓 Claude 對每個受管控的提示都依據您 AI 安全伺服器的判定進行把關，然後在對話方塊中確認，該對話方塊會重述您的失敗處理選擇。變更大約需要一分鐘才能傳達到每個 Anthropic 伺服器；已在處理中的請求會依舊設定完成。關閉它會停止將提示傳送到您的 AI 安全伺服器，同樣約在一分鐘內生效；您的設定會被保留。

   位於 Enforce verdicts 下方的 Validate tool calls 也會將 Claude 每個回應中的工具呼叫傳送到您的 AI 安全伺服器，並在執行前等待其判定；請參閱工具呼叫訊框。在新設定中它預設為開啟。當 Enforce verdicts 關閉時它不會有任何作用，且對它的變更與 Enforce verdicts 一樣，大約需要一分鐘才能傳達到每個 Anthropic 伺服器。

影子模式

「Shadow mode」（影子模式）會針對即時流量執行您的掛鉤，而不封鎖任何內容。您的 AI 安全伺服器會接收受管控的提示並傳回判定，方式與強制執行時完全相同，但不會封鎖任何內容：每個請求都會繼續傳送至模型，即使您的伺服器拒絕它或無法連線也是如此，且終端使用者不會察覺任何異狀。請使用它在開始強制執行之前，依據您組織的真實流量調整您的政策。開啟 Validate tool calls 時，您的伺服器在影子模式下也會接收工具呼叫訊框，且不會封鎖任何工具呼叫。

若要使用影子模式，請在 Failure handling 下將 Mode 設為 Shadow mode，然後開啟 Enforce verdicts，讓提示流向您的 AI 安全伺服器。當它處於啟用狀態時，設定頁面會顯示 Shadow mode — not blocking 標記。若要離開影子模式，請將 Mode 設回 Allow the request 或 Block the request；一旦強制執行開啟，裁決便會再次被強制執行。

排除項目

在 Exclusions 下，選擇其成員不受 Inference hooks 涵蓋的角色：他們的提示永遠不會被傳送至您的 AI 安全伺服器。只有您組織建立的自訂角色可以被排除；不提供內建角色。請在角色選擇器中挑選它們，其預留文字顯示為 Select roles to exclude，並從角色管理頁面（Manage roles）管理誰擁有各個角色；變更排除項目需要身分管理權限。此清單預設為空，在未排除任何角色的情況下，每個受管控的請求都會受到檢查。

排除適用於使用者的互動式工作階段。對排除清單的變更會以角色權限變更（rbac_role_permission_added 和 rbac_role_permission_removed）的形式記錄在您組織的活動摘要中。

自訂封鎖提示訊息

在 Custom blocked prompt message 下，設定最多 500 個字元的自訂文字，當您的 AI 安全伺服器拒絕請求時，此文字會附加在終端使用者看到的錯誤之後（通常是應聯繫誰或在何處申請例外）。最終訊息為您 AI 安全伺服器針對每個請求的 deny_reason（若有）、一個空行，然後是此文字。若未設定自訂文字，內建的預設訊息會引導使用者聯繫其管理員；您也可以完全關閉附加訊息，讓使用者只看到 deny_reason。

監控您的 AI 安全伺服器

Inference hooks 設定頁面的端點健康狀態區域會顯示：

• Endpoint status： Healthy、Tripped、Not enforcing，或在儲存端點之前顯示 Not configured。
• Failures per minute： 過去兩分鐘內 webhook 失敗次數的平均值。
• Block rate： 拒絕判定佔您 AI 安全伺服器判定的比例，在推出百分比低於 100 時顯示。
• Circuit breaker tripped： 斷路器上次跳脫的時間（若曾跳脫）。
• Recent errors： 每個項目會顯示失敗發生的時間、錯誤類型和類別。類別為 webhook_error 表示您的端點或與其連線有問題，為 relay_error 則表示 Anthropic 系統內部發生失敗。項目永遠不會包含請求內容或您的端點 URL。此清單會保留最近 10 次失敗，並在最後一次失敗的一小時後清除。

Recent errors 中的錯誤類型意義如下：

在影子模式下，任何錯誤都不會計入斷路器。

此面板為盡力而為：若 Anthropic 無法讀取計數器，它會顯示零次失敗且無錯誤，而非顯示其自身的錯誤，因此看起來健康的面板本身並不能證明您的 AI 安全伺服器是健康的。Failures per minute 會計算每一次失敗，包括永遠不會使斷路器跳脫的網路與 DNS 錯誤，因此它可能很高，而 Circuit breaker tripped 仍維持空白。

斷路器

可歸因於您 AI 安全伺服器的持續 webhook 失敗會使「circuit breaker」（斷路器）跳脫，進而停止強制執行：不再聯繫您的伺服器，且您的 Failure handling 選擇會套用至每個受檢查的請求。若選擇 Block the request，您組織中的使用者會被封鎖，直到斷路器重設為止。當斷路器跳脫時，管理員也會在 claude.ai 通知中心收到通知。

每次跳脫也會以 inference_hooks_circuit_breaker_tripped 活動記錄在您組織的活動摘要中，因此您的安全團隊或供應商可以透過他們已在運行的監控（例如擷取該摘要的 SIEM）對跳脫發出警示。每次跳脫記錄一個活動，而非每個受影響的請求記錄一個。記錄需要為您的組織啟用 Compliance API；請參閱設定 Compliance API。

若要復原，請修復伺服器，然後重新開啟 Enforce verdicts 以重設斷路器。

斷路器也可以自行重設。從跳脫後 10 分鐘開始，Anthropic 會在背景向您的伺服器傳送測試請求，以檢查伺服器是否已復原，頻率最多約每分鐘一次；此過程不涉及任何使用者請求。如果您的伺服器回應有效的判定（允許或拒絕皆可），斷路器就會重設，強制執行也會恢復。否則斷路器會維持跳脫狀態，檢查也會持續進行。

自動復原僅在您的 Inference hooks 設定自跳脫後未曾變更的情況下執行。如果您在跳脫後變更任何 Inference hooks 設定（包括輪替簽署密鑰），檢查就會停止，斷路器也不再自行重設；請在伺服器修復後重新開啟 Enforce verdicts。自動復原僅適用於跳脫：如果您自行關閉 Enforce verdicts，強制執行會維持關閉，直到您重新開啟為止。

輪替您的簽署密鑰

按一下 Request signing 下的 Rotate secret 以更換您的簽署密鑰。如果您的組織尚未有密鑰，同一個按鈕會顯示為 Generate secret，並建立第一個密鑰。輪替是立即切換：新密鑰會被產生並僅顯示一次，舊密鑰將無法再取得，且任何請求都不會同時以兩個密鑰簽署，因此沒有可依賴的重疊期間。

以先前密鑰簽署的請求在輪替後仍可能短暫抵達；驗證簽章說明了您的 AI 安全伺服器應如何處理切換。

稽核軌跡

Inference hooks 活動會記錄在您組織的活動摘要中：設定變更、拒絕、斷路器跳脫，以及因無法取得判定而在未經檢查的情況下繼續進行的請求。最後一種只有在 Enforce verdicts 開啟且 Mode 為 Allow the request 時才會記錄。其原因為 endpoint_timeout、呼叫您 AI 安全伺服器時發生任何其他問題的 endpoint_error，或 Anthropic 端失敗的 internal_error。在 Block the request 或 Shadow mode 下，失敗的請求不會個別記錄。斷路器的自動復原在任何模式下都不會被記錄。斷路器跳脫期間，不會記錄任何個別請求的 Inference hooks 活動；跳脫活動即為活動摘要中該期間的記錄。拒絕記錄帶有識別碼，讓您能將每個拒絕與您自己系統中的對應記錄進行關聯。

關閉 Inference hooks

關閉有兩個層級：

• 在 Inference hooks 設定頁面上關閉 Enforce verdicts：約在一分鐘內，您組織的提示會停止傳送至您的 AI 安全伺服器；已在處理中的請求會依舊設定完成。設定頁面仍可使用，因此請在您處理 AI 安全伺服器時使用此方式暫停強制執行。
• 在 Data and privacy 設定中關閉 Allow for your organization：提示不再受到檢查，且 Inference hooks 設定會變為無法使用，直到您重新開啟為止。無論哪種方式，您的端點設定、自訂標頭與簽署密鑰都會被保留；重新開啟會強制將 Enforce verdicts 設為關閉並清除已跳脫的斷路器，因此請在您準備好時再次開啟強制執行。

後續步驟