Arize Phoenix

Arize Phoenix 是來自 Arize AI 的開源 LLM 追蹤與評估專案。可用於本機開發、實驗，以及自架工作流程。

Phoenix 與 Arize AX 分開，後者是供生產團隊、AI 原生公司與企業使用的完整平台，可作為受管理雲端或企業自架部署使用。LiteLLM 支援兩種後端，但它們使用不同的回呼、憑證與端點。Phoenix 使用 arize_phoenix，AX 使用 arize，或在您需要將相同追蹤送往兩者時，同時啟用兩者。

對於圍繞 LiteLLM 追蹤建立評估迴圈的團隊，Arize 的 agent evaluation guide 與 LLM evaluation guide 涵蓋了用於追蹤失敗、評估模型行為，以及改善代理程式可靠性的生產工作流程。

資訊

我們希望了解如何讓這些回呼變得更好！認識 LiteLLM 的 founders 或 加入我們的 discord

前置需求

uv add litellm

快速開始

SDK

import litellm
import os

os.environ["LITELLM_OTEL_V2"] = "true"
os.environ["PHOENIX_API_KEY"] = ""
os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = "https://app.phoenix.arize.com/v1/traces"
os.environ["PHOENIX_PROJECT_NAME"] = ""   # optional, defaults to "default"
# LLM API Keys
os.environ["OPENAI_API_KEY"] = ""

# set arize_phoenix as a callback, litellm will send the data to phoenix
litellm.callbacks = ["arize_phoenix"]

# openai call
response = litellm.completion(
  model="gpt-5.6-terra",
  messages=[
    {"role": "user", "content": "Hi 👋 - i'm openai"}
  ]
)

LiteLLM Proxy

1. 設定 config.yaml

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY

litellm_settings:
  callbacks: ["arize_phoenix"]

2. 設定您的憑證

LITELLM_OTEL_V2=true
PHOENIX_API_KEY="your-api-key"
PHOENIX_COLLECTOR_ENDPOINT="https://app.phoenix.arize.com/v1/traces"
PHOENIX_PROJECT_NAME="my-project"   # optional

3. 啟動 LiteLLM Proxy

litellm --config /path/to/config.yaml

4. 測試它！

curl -L -X POST 'http://0.0.0.0:4000/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $LITELLM_API_KEY" \
-d '{
  "model": "gpt-5.6-terra",
  "messages": [
    {
      "role": "user",
      "content": "Hey, how are you?"
    }
  ]
}'

Phoenix 會呈現什麼

開啟 Phoenix；專案來自 PHOENIX_PROJECT_NAME（預設 default），並以 openinference.project.name 資源屬性標記。每個請求都會以 chat <model> span 的形式顯示在請求根節點下。在 proxy 上，您可以將團隊或金鑰的 LLM spans 傳送到不同的 Phoenix 專案；請參閱將追蹤依團隊或金鑰路由到 Phoenix 專案。

Phoenix 使用與 Arize AX 相同的 OpenInference 詞彙，因此 LLM 呼叫 span 會帶有 llm.model_name、llm.provider、llm.token_count.* 用量分割、llm.invocation_parameters、在啟用內容擷取時的訊息陣列，以及 llm.tools.*，以及標準的 gen_ai.* keys。請參閱完整屬性表。

設定

變數	必要	備註
PHOENIX_API_KEY	僅 Phoenix Cloud	當端點位於 app.phoenix.arize.com 上時必填；litellm 在沒有它時會拋出錯誤。自架 Phoenix 不需要
PHOENIX_COLLECTOR_HTTP_ENDPOINT	否	收集器端點；當兩者都設定時，優先於 PHOENIX_COLLECTOR_ENDPOINT
PHOENIX_COLLECTOR_ENDPOINT	否	收集器端點，當 HTTP 變數未設定時使用
PHOENIX_PROJECT_NAME	否	預設為 default；也可讀作 PHOENIX_COLLECTOR_PROJECT_NAME。當金鑰或團隊未設定 phoenix_project_name 時，這是備援專案

如果兩個端點變數都未設定，litellm 會回退到 http://localhost:6006/v1/traces。

協定是從端點推斷，而不是從變數名稱

這兩個變數都不綁定任何協定。litellm 會根據您提供的值選擇協定：以 grpc:// 開頭的端點，或包含 :4317 且沒有 /v1/traces 路徑的端點，會以 gRPC 匯出，其他任何情況則會以 HTTP 匯出。因此，Phoenix Cloud URL 可在任一變數中使用，而將 PHOENIX_COLLECTOR_ENDPOINT 指向 https://app.phoenix.arize.com/v1/traces 則會如預期般透過 HTTP 傳送。

選擇正確的收集器端點

Phoenix 有不只一種收集器端點形式，而選錯是最常見的 Phoenix 設定錯誤。請將端點指向與您的部署相符的形式：

部署	端點
Phoenix Cloud（Spaces）	https://app.phoenix.arize.com/s/<space-name>/v1/traces
Phoenix Cloud（舊版）	https://app.phoenix.arize.com/legacy/v1/traces
Phoenix Cloud（更早期）	https://app.phoenix.arize.com/v1/traces
自架	http://localhost:6006/v1/traces

依團隊或金鑰將追蹤路由到 Phoenix 專案

一個 Phoenix 收集器可以容納多個專案。在 LiteLLM proxy 上，將 phoenix_project_name 設定在團隊或虛擬金鑰上，讓該團隊（或該金鑰）的 LLM spans 進入他們自己的 Phoenix 專案。沒有專案名稱的金鑰會繼續使用 PHOENIX_PROJECT_NAME。

這就是您如何依團隊分割追蹤，而不必為每個租戶各自架設一個 Phoenix 執行個體。專案只會來自 proxy 在驗證時解析出的團隊或金鑰。若呼叫者在請求本文中放入 phoenix_project_name，會被忽略；呼叫仍會回傳 200，而且不會建立攻擊者所選的專案。

需要 OTel v2（LITELLM_OTEL_V2=true）與 callbacks: ["arize_phoenix"]。Phoenix 15.5.0+ 會尊重此處使用的 x-project-name 標頭；較舊的收集器會忽略它並維持使用環境變數中的專案。

依團隊

團隊中的每個金鑰都會將其 LLM spans 傳送到命名的專案。

curl -X POST 'http://localhost:4000/team/new' \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"team_alias": "payments", "metadata": {"phoenix_project_name": "payments-prod"}}'

以相同方式更新現有團隊：

curl -X POST 'http://localhost:4000/team/update' \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"team_id": "<team-id>", "metadata": {"phoenix_project_name": "payments-prod"}}'

接著為該團隊產生金鑰，並照常呼叫 proxy：

curl -X POST 'http://localhost:4000/key/generate' \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"team_id": "<team-id>"}'

curl -X POST 'http://localhost:4000/v1/chat/completions' \
  -H 'Authorization: Bearer $TEAM_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model": "gpt-5.6-terra", "messages": [{"role": "user", "content": "hello"}]}'

依金鑰

單一金鑰可以指定自己的專案名稱，包括不屬於任何團隊的金鑰。

curl -X POST 'http://localhost:4000/key/generate' \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"metadata": {"phoenix_project_name": "payments-canary"}}'

現有金鑰使用 /key/update 上相同的欄位。

您也可以在 Admin UI 中為團隊或金鑰設定相同的 metadata.phoenix_project_name 欄位。

在 chat（或 /v1/messages、/v1/responses）呼叫之後，Phoenix 會顯示一個名為 payments-prod 的專案，其中包含該請求的 chat <model> span。第二個設定了 phoenix_project_name: "search-prod" 的團隊會落到同一個收集器上的不同專案。

哪個專案會勝出

優先順序由高到低：

1. 金鑰或團隊上的 phoenix_project_name_override
2. 金鑰或團隊上的 phoenix_project_name
3. PHOENIX_PROJECT_NAME（或 PHOENIX_COLLECTOR_PROJECT_NAME），否則為 default

如果相同欄位同時設定在金鑰與團隊上，會使用團隊的值。當金鑰應該離開其團隊專案時，phoenix_project_name_override 是逃脫閥。

會被路由與不會被路由的內容

LLM 呼叫 span（chat <model>）是 Phoenix 用來建立並填入命名專案的 span。請求的 HTTP root、驗證與資料庫 spans 會留在環境變數設定的預設專案中。

Phoenix 會依其各個 spans 最先到達的是哪一個，將整個追蹤指派給單一專案。因此，被路由的 LLM span 會開始自己的追蹤，並帶有回到請求追蹤的連結，讓您仍然可以在兩者之間跳轉。

僅 gRPC 的 Phoenix exporter 無法路由：x-project-name 只在 OTLP/HTTP 上生效。請將 PHOENIX_COLLECTOR_HTTP_ENDPOINT 指向 HTTP /v1/traces URL（請參閱選擇正確的收集器端點）。防護欄 spans 不會進行專案路由。

這與依團隊的憑證不同，後者會將租戶的追蹤傳送到其自己的後端帳號。專案路由仍然只在同一個 Phoenix 收集器上進行，且只會變更專案名稱。

進階

同時傳送到 Phoenix 與 Arize AX

預設可以組合，因此您可以從一個 proxy 執行兩個後端：

litellm_settings:
  callbacks: ["arize_phoenix", "arize"]

完整的 OpenTelemetry 參考文件

此頁涵蓋 Phoenix 專屬設定。關於 span 屬性、prompt 與回應擷取、指標、分散式追蹤，以及哪些路由會被追蹤，請參閱OpenTelemetry v2 指南。

您是在尋找 prompt 管理而不是追蹤嗎？請參閱Arize Phoenix Prompt Management。

支援與聯絡創辦人

• 預約示範 👋
• 社群 Discord 💭
• 我們的電子郵件 ✉️ ishaan@berri.ai / krrish@berri.ai