phoenix-observability

Phoenix - AI オブザーバビリティプラットフォーム

トレース、評価、データセット、実験、リアルタイム監視を備えた、LLM アプリケーション向けのオープンソース AI オブザーバビリティ・評価プラットフォームです。

Phoenix を使用する場面

次のような場合に Phoenix を使用します。

• 詳細なトレースを使って LLM アプリケーションの問題をデバッグする
• データセットを使って体系的な評価を実施する
• 本番環境の LLM システムをリアルタイムで監視する
• プロンプトやモデルを比較するための実験パイプラインを構築する
• ベンダーロックインのないセルフホスト型のオブザーバビリティを利用する

主な機能：

• トレーシング：あらゆる LLM フレームワークに対応した、OpenTelemetry ベースのトレース収集
• 評価：品質評価のための LLM-as-judge 評価器
• データセット：回帰テスト用のバージョン管理されたテストセット
• 実験：プロンプト、モデル、設定を比較
• プレイグラウンド：複数のモデルを使った対話型プロンプトテスト
• オープンソース：PostgreSQL または SQLite を使ったセルフホストが可能

代わりに次を使用します。

• LangSmith：LangChain を優先した統合機能を備えたマネージドプラットフォーム
• Weights & Biases：ディープラーニングの実験追跡に特化
• Arize Cloud：エンタープライズ機能を備えたマネージド版 Phoenix
• MLflow：汎用的な ML ライフサイクルとモデルレジストリに特化

クイックスタート

インストール

pip install arize-phoenix

# With specific backends
pip install arize-phoenix[embeddings]  # Embedding analysis
pip install arize-phoenix-otel         # OpenTelemetry config
pip install arize-phoenix-evals        # Evaluation framework
pip install arize-phoenix-client       # Lightweight REST client

Phoenix サーバーを起動

import phoenix as px

# Launch in notebook (ThreadServer mode)
session = px.launch_app()

# View UI
session.view()  # Embedded iframe
print(session.url)  # http://localhost:6006

コマンドラインサーバー（本番環境）

# Start Phoenix server
phoenix serve

# With PostgreSQL
export PHOENIX_SQL_DATABASE_URL="postgresql://user:pass@host/db"
phoenix serve --port 6006

基本的なトレーシング

from phoenix.otel import register
from openinference.instrumentation.openai import OpenAIInstrumentor

# Configure OpenTelemetry with Phoenix
tracer_provider = register(
    project_name="my-llm-app",
    endpoint="http://localhost:6006/v1/traces"
)

# Instrument OpenAI SDK
OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

# All OpenAI calls are now traced
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

主な概念

トレースとスパン

トレースは実行フロー全体を表し、スパンはそのトレース内の個々の操作を表します。

from phoenix.otel import register
from opentelemetry import trace

# Setup tracing
tracer_provider = register(project_name="my-app")
tracer = trace.get_tracer(__name__)

# Create custom spans
with tracer.start_as_current_span("process_query") as span:
    span.set_attribute("input.value", query)

    # Child spans are automatically nested
    with tracer.start_as_current_span("retrieve_context"):
        context = retriever.search(query)

    with tracer.start_as_current_span("generate_response"):
        response = llm.generate(query, context)

    span.set_attribute("output.value", response)

プロジェクト

プロジェクトでは、関連するトレースを整理します。

import os
os.environ["PHOENIX_PROJECT_NAME"] = "production-chatbot"

# Or per-trace
from phoenix.otel import register
tracer_provider = register(project_name="experiment-v2")

フレームワークの計装

OpenAI

from phoenix.otel import register
from openinference.instrumentation.openai import OpenAIInstrumentor

tracer_provider = register()
OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

LangChain

from phoenix.otel import register
from openinference.instrumentation.langchain import LangChainInstrumentor

tracer_provider = register()
LangChainInstrumentor().instrument(tracer_provider=tracer_provider)

# All LangChain operations traced
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o")
response = llm.invoke("Hello!")

LlamaIndex

from phoenix.otel import register
from openinference.instrumentation.llama_index import LlamaIndexInstrumentor

tracer_provider = register()
LlamaIndexInstrumentor().instrument(tracer_provider=tracer_provider)

Anthropic

from phoenix.otel import register
from openinference.instrumentation.anthropic import AnthropicInstrumentor

tracer_provider = register()
AnthropicInstrumentor().instrument(tracer_provider=tracer_provider)

評価フレームワーク

組み込み評価器

from phoenix.evals import (
    OpenAIModel,
    HallucinationEvaluator,
    RelevanceEvaluator,
    ToxicityEvaluator,
    llm_classify
)

# Setup model for evaluation
eval_model = OpenAIModel(model="gpt-4o")

# Evaluate hallucination
hallucination_eval = HallucinationEvaluator(eval_model)
results = hallucination_eval.evaluate(
    input="What is the capital of France?",
    output="The capital of France is Paris.",
    reference="Paris is the capital of France."
)

カスタム評価器

from phoenix.evals import llm_classify

# Define custom evaluation
def evaluate_helpfulness(input_text, output_text):
    template = """
    Evaluate if the response is helpful for the given question.

    Question: {input}
    Response: {output}

    Is this response helpful? Answer 'helpful' or 'not_helpful'.
    """

    result = llm_classify(
        model=eval_model,
        template=template,
        input=input_text,
        output=output_text,
        rails=["helpful", "not_helpful"]
    )
    return result

データセットで評価を実行

from phoenix import Client
from phoenix.evals import run_evals

client = Client()

# Get spans to evaluate
spans_df = client.get_spans_dataframe(
    project_name="my-app",
    filter_condition="span_kind == 'LLM'"
)

# Run evaluations
eval_results = run_evals(
    dataframe=spans_df,
    evaluators=[
        HallucinationEvaluator(eval_model),
        RelevanceEvaluator(eval_model)
    ],
    provide_explanation=True
)

# Log results back to Phoenix
client.log_evaluations(eval_results)

データセットと実験

データセットを作成

from phoenix import Client

client = Client()

# Create dataset
dataset = client.create_dataset(
    name="qa-test-set",
    description="QA evaluation dataset"
)

# Add examples
client.add_examples_to_dataset(
    dataset_name="qa-test-set",
    examples=[
        {
            "input": {"question": "What is Python?"},
            "output": {"answer": "A programming language"}
        },
        {
            "input": {"question": "What is ML?"},
            "output": {"answer": "Machine learning"}
        }
    ]
)

実験を実行

from phoenix import Client
from phoenix.experiments import run_experiment

client = Client()

def my_model(input_data):
    """Your model function."""
    question = input_data["question"]
    return {"answer": generate_answer(question)}

def accuracy_evaluator(input_data, output, expected):
    """Custom evaluator."""
    return {
        "score": 1.0 if expected["answer"].lower() in output["answer"].lower() else 0.0,
        "label": "correct" if expected["answer"].lower() in output["answer"].lower() else "incorrect"
    }

# Run experiment
results = run_experiment(
    dataset_name="qa-test-set",
    task=my_model,
    evaluators=[accuracy_evaluator],
    experiment_name="baseline-v1"
)

print(f"Average accuracy: {results.aggregate_metrics['accuracy']}")

クライアント API

トレースとスパンをクエリ

from phoenix import Client

client = Client(endpoint="http://localhost:6006")

# Get spans as DataFrame
spans_df = client.get_spans_dataframe(
    project_name="my-app",
    filter_condition="span_kind == 'LLM'",
    limit=1000
)

# Get specific span
span = client.get_span(span_id="abc123")

# Get trace
trace = client.get_trace(trace_id="xyz789")

フィードバックを記録

from phoenix import Client

client = Client()

# Log user feedback
client.log_annotation(
    span_id="abc123",
    name="user_rating",
    annotator_kind="HUMAN",
    score=0.8,
    label="helpful",
    metadata={"comment": "Good response"}
)

データをエクスポート

# Export to pandas
df = client.get_spans_dataframe(project_name="my-app")

# Export traces
traces = client.list_traces(project_name="my-app")

本番環境へのデプロイ

Docker

docker run -p 6006:6006 arizephoenix/phoenix:latest

PostgreSQL を使用

# Set database URL
export PHOENIX_SQL_DATABASE_URL="postgresql://user:pass@host:5432/phoenix"

# Start server
phoenix serve --host 0.0.0.0 --port 6006

環境変数

変数	説明	デフォルト
PHOENIX_PORT	HTTP サーバーのポート	6006
PHOENIX_HOST	サーバーのバインドアドレス	127.0.0.1
PHOENIX_GRPC_PORT	gRPC/OTLP ポート	4317
PHOENIX_SQL_DATABASE_URL	データベース接続	SQLite の一時領域
PHOENIX_WORKING_DIR	データ保存ディレクトリ	OS の一時領域
PHOENIX_ENABLE_AUTH	認証を有効化	false
PHOENIX_SECRET	JWT 署名シークレット	認証を有効にする場合は必須

認証を使用

export PHOENIX_ENABLE_AUTH=true
export PHOENIX_SECRET="your-secret-key-min-32-chars"
export PHOENIX_ADMIN_SECRET="admin-bootstrap-token"

phoenix serve

ベストプラクティス

1. プロジェクトを使用する：環境（dev/staging/prod）ごとにトレースを分けます
2. メタデータを追加する：デバッグ用にユーザー ID、セッション ID を含めます
3. 定期的に評価する：CI/CD で自動評価を実行します
4. データセットをバージョン管理する：テストセットの変更を継続的に追跡します
5. コストを監視する：Phoenix のダッシュボードでトークン使用量を追跡します
6. セルフホストする：本番環境へのデプロイには PostgreSQL を使用します

よくある問題

トレースが表示されない場合：

from phoenix.otel import register

# Verify endpoint
tracer_provider = register(
    project_name="my-app",
    endpoint="http://localhost:6006/v1/traces"  # Correct endpoint
)

# Force flush
from opentelemetry import trace
trace.get_tracer_provider().force_flush()

ノートブックでメモリ使用量が多い場合：

# Close session when done
session = px.launch_app()
# ... do work ...
session.close()
px.close_app()

データベース接続の問題：

# Verify PostgreSQL connection
psql $PHOENIX_SQL_DATABASE_URL -c "SELECT 1"

# Check Phoenix logs
phoenix serve --log-level debug

参考資料

• 応用的な使用方法 - カスタム評価器、実験、本番環境のセットアップ
• トラブルシューティング - よくある問題、デバッグ、パフォーマンス

リソース

• ドキュメント：https://docs.arize.com/phoenix
• リポジトリ：https://github.com/Arize-ai/phoenix
• Docker Hub：https://hub.docker.com/r/arizephoenix/phoenix
• バージョン：12.0.0+
• ライセンス：Apache 2.0

関連スキル

• langsmith-observability：トレーシング、評価、監視に対応した LLM オブザーバビリティプラットフォーム。
• chroma：AI アプリケーション向けのオープンソース埋め込みデータベース。
• speculative-decoding：投機的デコーディング、Medusa の複数ヘッド、ルックアヘッドデコーディング技術を使って LLM の推論を高速化します。