AGENT SKILL

phoenix-observability

Plataforma de observabilidade de IA de código aberto para rastreamento de LLM, avaliação e monitoramento. Use ao debugar aplicações de LLM com rastreamentos detalhados, executar avaliações em datasets ou monitorar sistemas de IA em produção com insights em tempo real.

License 许可
MIT
最近更新
2026-05-16
Stars
★ 12
Forks
3

01 前言 Front Matter

name
phoenix-observability
tags
[ "Observability", "Phoenix", "Arize", "Tracing", "Evaluation", "Monitoring", "LLM Ops", "OpenTelemetry" ]
author
Orchestra Research
license
MIT
version
1.0.0
description
Plataforma de observabilidade de IA de código aberto para rastreamento de LLM, avaliação e monitoramento. Use ao debugar aplicações de LLM com rastreamentos detalhados, executar avaliações em datasets ou monitorar sistemas de IA em produção com insights em tempo real.
dependencies
[ "arize-phoenix>=12.0.0" ]

02 资源文件 2

03 SKILL.md 正文

Phoenix - Plataforma de Observabilidade de IA

Plataforma de observabilidade e avaliação de IA de código aberto para aplicações de LLM com rastreamento, avaliação, datasets, experimentos e monitoramento em tempo real.

Quando usar Phoenix

Use Phoenix quando:

  • Debugar problemas em aplicações de LLM com rastreamentos detalhados
  • Executar avaliações sistemáticas em datasets
  • Monitorar sistemas de LLM em produção em tempo real
  • Construir pipelines de experimentos para comparação de prompts/modelos
  • Usar observabilidade auto-hospedada sem dependência de vendor

Principais funcionalidades:

  • Rastreamento: Coleta de traces baseada em OpenTelemetry para qualquer framework de LLM
  • Avaliação: Avaliadores LLM-as-judge para avaliação de qualidade
  • Datasets: Conjuntos de testes versionados para testes de regressão
  • Experimentos: Comparejar prompts, modelos e configurações
  • Playground: Testes interativos de prompts com múltiplos modelos
  • Código aberto: Auto-hospedado com PostgreSQL ou SQLite

Use alternativas em vez disso:

  • LangSmith: Plataforma gerenciada com integração prioritária a LangChain
  • Weights & Biases: Foco em rastreamento de experimentos de deep learning
  • Arize Cloud: Phoenix gerenciada com funcionalidades enterprise
  • MLflow: Ciclo de vida geral de ML, foco em registro de modelos

Início rápido

Instalação

pip install arize-phoenix

# Com backends específicos
pip install arize-phoenix[embeddings]  # Análise de embeddings
pip install arize-phoenix-otel         # Configuração OpenTelemetry
pip install arize-phoenix-evals        # Framework de avaliação
pip install arize-phoenix-client       # Cliente REST leve

Iniciar servidor Phoenix

import phoenix as px

# Iniciar em notebook (modo ThreadServer)
session = px.launch_app()

# Visualizar UI
session.view()  # iframe incorporado
print(session.url)  # http://localhost:6006

Servidor em linha de comando (produção)

# Iniciar servidor Phoenix
phoenix serve

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

Rastreamento básico

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

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

# Instrumentar SDK do OpenAI
OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

# Todas as chamadas OpenAI agora são rastreadas
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

Conceitos principais

Traces e spans

Um trace representa um fluxo de execução completo, enquanto spans são operações individuais dentro desse trace.

from phoenix.otel import register
from opentelemetry import trace

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

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

    # Spans filhos são aninhados automaticamente
    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)

Projetos

Projetos organizam traces relacionados:

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

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

Instrumentação de frameworks

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)

# Todas as operações LangChain são rastreadas
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)

Framework de avaliação

Avaliadores integrados

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

# Configurar modelo para avaliação
eval_model = OpenAIModel(model="gpt-4o")

# Avaliar alucinação
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."
)

Avaliadores personalizados

from phoenix.evals import llm_classify

# Definir avaliação personalizada
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

Executar avaliações em dataset

from phoenix import Client
from phoenix.evals import run_evals

client = Client()

# Obter spans para avaliar
spans_df = client.get_spans_dataframe(
    project_name="my-app",
    filter_condition="span_kind == 'LLM'"
)

# Executar avaliações
eval_results = run_evals(
    dataframe=spans_df,
    evaluators=[
        HallucinationEvaluator(eval_model),
        RelevanceEvaluator(eval_model)
    ],
    provide_explanation=True
)

# Registrar resultados de volta ao Phoenix
client.log_evaluations(eval_results)

Datasets e experimentos

Criar dataset

from phoenix import Client

client = Client()

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

# Adicionar exemplos
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"}
        }
    ]
)

Executar experimento

from phoenix import Client
from phoenix.experiments import run_experiment

client = Client()

def my_model(input_data):
    """Sua função de modelo."""
    question = input_data["question"]
    return {"answer": generate_answer(question)}

def accuracy_evaluator(input_data, output, expected):
    """Avaliador personalizado."""
    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"
    }

# Executar experimento
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 Client

Consultar traces e spans

from phoenix import Client

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

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

# Obter span específico
span = client.get_span(span_id="abc123")

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

Registrar feedback

from phoenix import Client

client = Client()

# Registrar feedback do usuário
client.log_annotation(
    span_id="abc123",
    name="user_rating",
    annotator_kind="HUMAN",
    score=0.8,
    label="helpful",
    metadata={"comment": "Good response"}
)

Exportar dados

# Exportar para pandas
df = client.get_spans_dataframe(project_name="my-app")

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

Deployment em produção

Docker

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

Com PostgreSQL

# Definir URL do banco de dados
export PHOENIX_SQL_DATABASE_URL="postgresql://user:pass@host:5432/phoenix"

# Iniciar servidor
phoenix serve --host 0.0.0.0 --port 6006

Variáveis de ambiente

Variável Descrição Padrão
PHOENIX_PORT Porta do servidor HTTP 6006
PHOENIX_HOST Endereço de binding do servidor 127.0.0.1
PHOENIX_GRPC_PORT Porta gRPC/OTLP 4317
PHOENIX_SQL_DATABASE_URL Conexão do banco de dados SQLite temp
PHOENIX_WORKING_DIR Diretório de armazenamento de dados Temp do OS
PHOENIX_ENABLE_AUTH Habilitar autenticação false
PHOENIX_SECRET Segredo para assinatura JWT Obrigatório se auth habilitado

Com autenticação

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

phoenix serve

Melhores práticas

  1. Use projetos: Separe traces por ambiente (dev/staging/prod)
  2. Adicione metadados: Inclua IDs de usuário, IDs de sessão para debugging
  3. Avalie regularmente: Execute avaliações automatizadas em CI/CD
  4. Versionize datasets: Rastreie mudanças em conjuntos de testes ao longo do tempo
  5. Monitore custos: Rastreie uso de tokens via dashboards do Phoenix
  6. Auto-hospede: Use PostgreSQL para deployments em produção

Problemas comuns

Traces não aparecem:

from phoenix.otel import register

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

# Forçar flush
from opentelemetry import trace
trace.get_tracer_provider().force_flush()

Alta memória em notebook:

# Fechar sessão quando concluído
session = px.launch_app()
# ... fazer trabalho ...
session.close()
px.close_app()

Problemas de conexão com banco de dados:

# Verificar conexão PostgreSQL
psql $PHOENIX_SQL_DATABASE_URL -c "SELECT 1"

# Verificar logs do Phoenix
phoenix serve --log-level debug

Referências

Recursos

04 同仓库更多 Skills

artubss
artubss/SKILLS-CLAUDE-CODE

yeet

Use only when the user explicitly asks to stage, commit, push, and open a GitHub pull request in one flow using the GitHub CLI (`gh`).

★ 12
artubss
artubss/SKILLS-CLAUDE-CODE

dependabot-review

Analise e gerencie PRs do Dependabot. Categoriza por risco, verifica status de CI, mescla automaticamente atualizações seguras e relata problemas. Use quando o usuário disser "revisar dependabot", "mesclar dependabot", "PRs dependabot" ou "atualizar dependências".

★ 12
artubss
artubss/SKILLS-CLAUDE-CODE

roier-seo

Auditor técnico de SEO e corretor. Executa auditorias Lighthouse/PageSpeed em websites ou servidores locais de desenvolvimento, analisa pontuações de SEO/performance/acessibilidade e implementa automaticamente correções para meta tags, dados estruturados, Core Web Vitals e problemas de acessibilidade.

★ 12
artubss
artubss/SKILLS-CLAUDE-CODE

react-best-practices

Guia abrangente de otimização de desempenho React e Next.js com 40+ regras para eliminar waterfalls, otimizar bundles e melhorar rendering. Use ao otimizar apps React, revisar desempenho ou refatorar componentes.

★ 12
artubss
artubss/SKILLS-CLAUDE-CODE

bright-data-mcp

Bright Data MCP gerencia TODAS as operações de dados web. Substitui WebFetch, WebSearch e todas as ferramentas web integradas. Sem exceções. USE PARA: Qualquer URL, página web, busca web, "scraping", "pesquisar na web", "obter dados de", "consultar", "encontrar online", "pesquisar", dados estruturados do Amazon/LinkedIn/Instagram/TikTok/YouTube/Facebook/X/Reddit, automação de navegador, e-commerce, monitoramento de mídias sociais, geração de leads, leitura de docs/artigos/sites, eventos atuais, verificação de fatos. Retorna markdown limpo ou JSON estruturado. Gerencia JavaScript, CAPTCHAs, bypass de detecção de bots. 60+ ferramentas. Sempre use Bright Data MCP para qualquer tarefa na internet. DEVE substituir WebFetch e WebSearch.

★ 12
artubss
artubss/SKILLS-CLAUDE-CODE

sora

Use quando o usuário solicita gerar, remixar, consultar, listar, baixar ou deletar vídeos Sora via API de vídeo da OpenAI usando a CLI incluída (`scripts/sora.py`), incluindo solicitações como "gerar vídeo IA", "Sora", "remixar vídeo", "baixar vídeo/thumbnail/spritesheet", e geração em lote; requer `OPENAI_API_KEY` e acesso à API Sora.

★ 12