\n),\ninlineCode: ({ children, className }) => (\n \n {children}\n \n),\n```\n\n资料来源：[app/src/components/markdown/streamdownComponents.tsx:1-60]()\n\n### Playground Components\n\n#### PromptMenu\n\nTabbed interface for managing prompt versions and tags. Uses lazy-loaded tabs for performance.\n\n```typescript\n\n \n \n \n \n \n \n\n```\n\n| Tab | Content |\n|-----|---------|\n| Versions | Prompt version history |\n| Tags | Tag management |\n\n资料来源：[app/src/pages/playground/PromptMenu.tsx:1-80]()\n\n### Tool Components\n\n#### DocsToolDetails\n\nRenders documentation tool outputs with state-based display logic.\n\n```typescript\nfunction getOutputText(part: ToolInvocationPart): string {\n if (part.state !== \"output-available\" || part.output == null) {\n return \"\";\n }\n return stringifyToolValue(part.output);\n}\n\n// Preview truncation for long outputs\nexport function truncateDocsOutput(text: string): string {\n if (text.length <= OUTPUT_PREVIEW_LENGTH) {\n return text;\n }\n return text.slice(0, OUTPUT_PREVIEW_LENGTH) + \"…\";\n}\n```\n\n资料来源：[app/src/components/agent/DocsToolDetails.tsx:1-100]()\n\n### UI Components\n\n#### Icons\n\nSVG icon components using `currentColor` for theme compatibility.\n\n```typescript\nexport const ArrowCompareOutline = () => (\n \n);\n```\n\nAvailable icons include: `ArrowCompareOutline`, `TemplateOutline`, `FileOutline`, `CloseOutline`, and more.\n\n资料来源：[app/src/components/core/icon/Icons.tsx:1-50]()\n\n#### FileListItem\n\nReusable file upload item component with progress tracking and status indicators.\n\n| Status | Description |\n|--------|-------------|\n| `uploading` | File transfer in progress |\n| `parsing` | File content being processed |\n| `complete` | Upload and parse successful |\n| `error` | Upload or parse failed |\n\n```typescript\nconst showProgress = status !== \"complete\" && progress !== undefined;\n\nreturn (\n
\n \n
\n);\n```\n\n资料来源：[app/src/components/core/dropzone/FileListItem.tsx:1-70]()\n\n## Context Providers\n\n### Provider Hierarchy\n\n```mermaid\ngraph TD\n A[TracingRoot] --> B[TracePaginationProvider]\n B --> C[SpanFiltersProvider]\n C --> D[TracesTabContent]\n \n E[IsAuthenticated] --> F[IsAdmin]\n F --> G[GenerateAPIKeyButton]\n```\n\n| Provider | Purpose |\n|----------|---------|\n| `TracingRoot` | Global tracing state |\n| `TracePaginationProvider` | Pagination state for traces |\n| `SpanFiltersProvider` | Filter state for span queries |\n| `IsAuthenticated` | Authentication state check |\n| `IsAdmin` | Authorization check |\n\n## Environment Configuration\n\n### Phoenix Environment Variables\n\nThe frontend reads configuration from environment variables via the `@arizeai/phoenix-config` package.\n\n| Variable | Constant | Description |\n|----------|----------|-------------|\n| `PHOENIX_HOST` | `ENV_PHOENIX_HOST` | Phoenix server host URL |\n| `PHOENIX_API_KEY` | `ENV_PHOENIX_API_KEY` | API key for authentication |\n| `PHOENIX_CLIENT_HEADERS` | `ENV_PHOENIX_CLIENT_HEADERS` | JSON-encoded custom headers |\n| `PHOENIX_COLLECTOR_ENDPOINT` | `ENV_PHOENIX_COLLECTOR_ENDPOINT` | OTel collector endpoint |\n| `PHOENIX_PORT` | `ENV_PHOENIX_PORT` | Phoenix HTTP port |\n| `PHOENIX_GRPC_PORT` | `ENV_PHOENIX_GRPC_PORT` | Phoenix gRPC port |\n| `PHOENIX_PROJECT` | `ENV_PHOENIX_PROJECT` | Default project name |\n\n资料来源：[js/packages/phoenix-config/README.md:1-50]()\n\n### Runtime Configuration\n\n```typescript\nconst isHosted = IS_HOSTED_DEPLOYMENT;\nconst isAuthEnabled = window.Config.authenticationEnabled;\n```\n\n## Data Flow\n\n### Trace Navigation Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant TracesTable\n participant ProjectTracesPage\n participant API\n \n User->>TracesTable: Click trace row\n TracesTable->>TracesTable: Get row trace data\n TracesTable->>User: Navigate to trace detail\n User->>ProjectTracesPage: Load trace by ID\n ProjectTracesPage->>API: Fetch trace data\n API-->>ProjectTracesPage: Return trace\n ProjectTracesPage-->>User: Render TraceTree\n```\n\n### Annotation Flow\n\n```mermaid\ngraph LR\n A[TraceView] --> B[AnnotationLabel]\n B --> C[AnnotationTooltip]\n C --> D[External Link]\n D --> E[Trace Detail]\n \n A --> F[AnnotationConfigList]\n F --> G[Create Annotation]\n```\n\n## Package Dependencies\n\n### Key Dependencies\n\n| Package | Version Constraint | Purpose |\n|---------|-------------------|---------|\n| `react` | `>=18.0.0` | Core framework |\n| `react-router-dom` | `>=6.0.0` | Routing |\n| `@tanstack/react-table` | Latest | Data tables |\n| `@adobe/react-spectrum` | Latest | UI components |\n| `@arizeai/phoenix-evals` | Latest | Evaluation functions |\n| `@arizeai/phoenix-config` | Latest | Config utilities |\n\n资料来源：[app/package.json:1-50]()\n\n## Best Practices\n\n### Component Patterns\n\n1. **Lazy Loading**: Use `Suspense` with lazy-loaded components for route-based code splitting\n2. **Context Composition**: Wrap related state in dedicated providers\n3. **Type Safety**: Use TypeScript interfaces for all component props\n4. **CSS Organization**: Use CSS-in-JS with semantic class naming\n\n### Performance Considerations\n\n- Implement virtual scrolling for large trace lists\n- Use `React.memo` for expensive component re-renders\n- Lazy load tab panels in tabbed interfaces\n- Truncate long outputs in preview contexts\n\n```typescript\nexport function truncateDocsOutput(text: string): string {\n if (text.length <= OUTPUT_PREVIEW_LENGTH) {\n return text;\n }\n return text.slice(0, OUTPUT_PREVIEW_LENGTH) + \"…\";\n}\n\n---\n\n\n\n## Server API and GraphQL\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture), [Database Models and Migrations](#page-database-models)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/phoenix/server/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/__init__.py)\n- [src/phoenix/server/api/context.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/context.py)\n- [src/phoenix/server/api/auth.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/auth.py)\n- [src/phoenix/server/api/dataloaders/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/dataloaders/__init__.py)\n- [src/phoenix/server/api/routers/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/routers/__init__.py)\n\n\n# Server API and GraphQL\n\nPhoenix provides a comprehensive server API layer built on GraphQL (via Strawberry) and REST endpoints for managing traces, experiments, datasets, and evaluations. The API architecture is designed for observability, authentication, and efficient data loading.\n\n## Architecture Overview\n\nPhoenix's server API follows a layered architecture that separates concerns between request handling, authentication, data access, and response rendering.\n\n```mermaid\ngraph TD\n A[Client Request] --> B[API Router Layer]\n B --> C[Authentication Middleware]\n C --> D[Context Builder]\n D --> E[GraphQL Executor / REST Handler]\n E --> F[Data Loaders]\n F --> G[Database / Storage]\n G --> H[Response]\n```\n\n## Core Components\n\n### Server Initialization\n\nThe main server module (`src/phoenix/server/__init__.py`) orchestrates the application lifecycle, including database initialization, API router setup, and background task management.\n\n| Component | Purpose | Key Responsibilities |\n|-----------|---------|---------------------|\n| `Server` | Main application class | Initialize app, setup routes, manage lifecycle |\n| `App` | ASGI application | Handle HTTP/WebSocket connections |\n| `Database` | Data persistence | SQLite/PostgreSQL connection management |\n\n资料来源：[src/phoenix/server/__init__.py:1-50]()\n\n### Request Context\n\nThe context module (`src/phoenix/server/api/context.py`) provides request-scoped data access throughout the API layer. It manages database sessions, user authentication, and configuration access.\n\n```python\nclass Context:\n def __init__(\n self,\n db: Session,\n user: User | None,\n data_loaders: dict[str, DataLoader],\n ) -> None:\n self.db = db\n self.user = user\n self.data_loaders = data_loaders\n```\n\n**Key Context Properties:**\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `db` | `Session` | SQLAlchemy database session |\n| `user` | `User \\| None` | Authenticated user or anonymous |\n| `data_loaders` | `dict[str, DataLoader]` | Batch data loading utilities |\n| `has_auth` | `bool` | Whether authentication is enabled |\n\n资料来源：[src/phoenix/server/api/context.py:1-100]()\n\n## Authentication System\n\nThe authentication module (`src/phoenix/server/api/auth.py`) implements token-based authentication for API access.\n\n### Authentication Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant API\n participant Auth\n participant DB\n \n Client->>API: Request + API Key\n API->>Auth: Validate Token\n Auth->>DB: Lookup User\n DB-->>Auth: User Record\n Auth-->>API: Authenticated Context\n API-->>Client: Response with Context\n```\n\n### Authentication Methods\n\n| Method | Header | Description |\n|--------|--------|-------------|\n| API Key | `Authorization: Bearer ` | Token-based authentication |\n| Session | Cookie-based | Web UI authentication |\n| Anonymous | None | Read-only access when auth disabled |\n\n### Permission Classes\n\nPhoenix enforces permission checks on mutations and subscriptions:\n\n- `IsNotReadOnly` - Prevents read-only users from modifying data\n- `IsNotViewer` - Prevents viewer roles from write operations\n\n资料来源：[src/phoenix/server/api/auth.py:1-80]()\n\n## GraphQL Schema\n\nPhoenix uses Strawberry GraphQL for its primary API surface, enabling type-safe queries and mutations with automatic documentation.\n\n### Schema Structure\n\n```\nQuery\n├── datasets\n│ ├── get_dataset\n│ └── get_dataset_by_id\n├── experiments\n│ ├── experiments\n│ └── experiment_by_id\n├── projects\n│ ├── projects\n│ └── project_by_id\n├── spans\n│ └── get_spans\n└── traces\n └── get_traces\n\nMutation\n├── datasets\n│ ├── create_dataset\n│ ├── upload_dataset\n│ └── delete_dataset\n├── experiments\n│ ├── create_experiment\n│ └── run_experiment\n├── spans\n│ └── create_span_annotation\n└── traces\n └── create_trace_annotation\n```\n\n### Data Loaders\n\nData loaders (`src/phoenix/server/api/dataloaders/`) implement the N+1 query problem solution through batch loading and caching within request scope.\n\n```python\nclass DatasetLoader(DataLoader[int, Dataset]):\n def batch_load(self, dataset_ids: list[int]) -> list[Dataset]:\n # Single database query for all IDs\n datasets = self.db.query(Dataset).filter(Dataset.id.in_(dataset_ids)).all()\n return datasets\n```\n\n| DataLoader | Purpose |\n|------------|---------|\n| `DatasetLoader` | Batch load datasets by ID |\n| `ProjectLoader` | Batch load projects by ID |\n| `SpanLoader` | Batch load spans by ID |\n| `AnnotationLoader` | Batch load annotations |\n| `UserLoader` | Batch load user records |\n\n资料来源：[src/phoenix/server/api/dataloaders/__init__.py:1-50]()\n\n## REST API Endpoints\n\n### API Router Structure\n\n```python\n# src/phoenix/server/api/routers/__init__.py\nrouters = [\n datasets_router,\n experiments_router,\n spans_router,\n traces_router,\n evaluations_router,\n]\n```\n\n### Dataset Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/v1/datasets` | List all datasets |\n| `POST` | `/v1/datasets` | Create new dataset |\n| `GET` | `/v1/datasets/{id}` | Get dataset by ID |\n| `PUT` | `/v1/datasets/{id}` | Update dataset |\n| `DELETE` | `/v1/datasets/{id}` | Delete dataset |\n| `POST` | `/v1/datasets/{id}/upload` | Upload data to dataset |\n\n### Experiment Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/v1/experiments` | List experiments |\n| `POST` | `/v1/experiments` | Create experiment |\n| `GET` | `/v1/experiments/{id}` | Get experiment details |\n| `POST` | `/v1/experiments/{id}/run` | Run experiment evaluation |\n\n### Span and Trace Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/v1/spans` | Query spans with filtering |\n| `POST` | `/v1/spans/{id}/annotations` | Add span annotation |\n| `GET` | `/v1/traces` | Query traces |\n| `POST` | `/v1/traces/{id}/annotations` | Add trace annotation |\n\n资料来源：[src/phoenix/server/api/routers/__init__.py:1-30]()\n\n## OpenAPI Schema\n\nPhoenix exposes its REST API through an OpenAPI schema that can be compiled for documentation and client generation:\n\n```bash\npython scripts/ci/compile_openapi_schema.py\n```\n\nThis generates the schema at `openapi-schema.json` for validation and client SDK generation.\n\n资料来源：[scripts/README.md:1-50]()\n\n## Environment Variables\n\nThe API server recognizes the following configuration variables:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `PHOENIX_HOST` | Server host URL | `http://localhost:6006` |\n| `PHOENIX_PORT` | HTTP port | `6006` |\n| `PHOENIX_GRPC_PORT` | gRPC port | `4317` |\n| `PHOENIX_API_KEY` | Authentication key | None |\n| `PHOENIXCollectorEndpoint` | OTEL collector endpoint | Internal |\n\n## Client Integration\n\n### Python Client\n\n```python\nfrom phoenix.client import Client\n\nclient = Client(\n host=\"http://localhost:6006\",\n api_key=\"your-api-key\"\n)\n\n# Query datasets\ndatasets = client.datasets.list()\n\n# Get spans as DataFrame\nspans = client.spans.get_spans_dataframe(\n project_identifier=\"my-project\",\n limit=1000\n)\n```\n\n### TypeScript Client\n\n```typescript\nimport { Client } from \"@arizeai/phoenix-client\";\n\nconst client = new Client({\n host: \"http://localhost:6006\",\n apiKey: \"your-api-key\"\n});\n\nconst datasets = await client.datasets.list();\n```\n\n## Request/Response Patterns\n\n### GraphQL Query Example\n\n```graphql\nquery GetDataset($id: GlobalID!) {\n dataset(id: $id) {\n id\n name\n version\n createdAt\n spanCount\n traceCount\n }\n}\n```\n\n### REST Request with Filtering\n\n```bash\ncurl -X GET \"http://localhost:6006/v1/spans?project_id=abc123&limit=100\" \\\n -H \"Authorization: Bearer $PHOENIX_API_KEY\"\n```\n\n## Summary\n\nPhoenix's Server API and GraphQL layer provides a unified interface for observability operations:\n\n- **GraphQL** via Strawberry for type-safe, self-documenting queries\n- **REST** endpoints for compatibility and specialized operations\n- **Authentication** via API keys with role-based permissions\n- **Data Loaders** for efficient batch data loading\n- **OpenAPI schema** for client SDK generation\n\n---\n\n\n\n## Python SDK (arize-phoenix-client)\n\n### 相关页面\n\n相关主题：[Evaluation System (Phoenix Evals)](#page-evals-system), [OpenTelemetry Integration](#page-otel-integration)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/phoenix-client/src/phoenix/client/client.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/client.py)\n- [packages/phoenix-client/src/phoenix/client/resources](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/resources)\n- [packages/phoenix-client/src/phoenix/client/helpers/sdk](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/helpers/sdk)\n- [packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/README.md)\n- [src/phoenix/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/__init__.py)\n\n\n# Python SDK (arize-phoenix-client)\n\nThe `arize-phoenix-client` is the official Python SDK for Arize Phoenix, providing a comprehensive interface for interacting with the Phoenix platform via its REST API. This SDK enables developers to programmatically manage datasets, run experiments, analyze traces, and collect feedback for LLM observability and evaluation workflows.\n\n## Overview\n\nPhoenix is an open-source AI observability platform designed for debugging, evaluating, and refining LLM applications. The Python SDK serves as the primary programmatic interface for:\n\n- **REST API Integration** - Full access to Phoenix's OpenAPI REST interface\n- **Prompt Management** - Create, version, and invoke prompt templates\n- **Dataset Operations** - Create and append datasets from DataFrames, CSV files, or dictionaries\n- **Experiment Tracking** - Run evaluations and track experiment results\n- **Trace Analysis** - Query and analyze traces with powerful filtering capabilities\n- **Annotation Workflows** - Add human feedback and automated evaluations to spans\n\n资料来源：[packages/phoenix-client/README.md]()\n\n## Installation\n\nInstall the SDK using pip:\n\n```bash\npip install arize-phoenix-client\n```\n\n资料来源：[packages/phoenix-client/README.md]()\n\n## Client Initialization\n\nThe SDK provides both synchronous and asynchronous client implementations.\n\n### Synchronous Client\n\n```python\nfrom phoenix.client import Client\n\n# Automatic configuration from environment variables\nclient = Client()\n\n# Explicit configuration\nclient = Client(base_url=\"http://localhost:6006\")\n\n# Cloud instance with API key\nclient = Client(\n base_url=\"https://app.phoenix.arize.com/s/your-space\",\n api_key=\"your-api-key\"\n)\n```\n\n### Asynchronous Client\n\n```python\nfrom phoenix.client import Client, AsyncClient\n\n# Create async client with same configuration options\nasync_client = AsyncClient()\nasync_client = AsyncClient(base_url=\"http://localhost:6006\")\nasync_client = AsyncClient(\n base_url=\"https://app.phoenix.arize.com/s/your-space\",\n api_key=\"your-api-key\"\n)\n```\n\n资料来源：[packages/phoenix-client/README.md]()\n\n## Configuration\n\n### Environment Variables\n\nThe client automatically reads configuration from environment variables:\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `PHOENIX_BASE_URL` | Base URL of the Phoenix server | `http://localhost:6006` |\n| `PHOENIX_API_KEY` | API key for authentication | `sk-xxxxx` |\n| `PHOENIX_CLIENT_HEADERS` | Custom headers (JSON stringified) | `{\"Authorization\": \"Bearer xxx\"}` |\n\n### Configuration Examples\n\n```bash\n# Local Phoenix server (default)\nexport PHOENIX_BASE_URL=\"http://localhost:6006\"\n\n# Cloud Instance\nexport PHOENIX_API_KEY=\"your-api-key\"\nexport PHOENIX_BASE_URL=\"https://app.phoenix.arize.com/s/your-space\"\n\n# Custom Headers\nexport PHOENIX_CLIENT_HEADERS=\"Authorization=Bearer your-api-key,custom-header=value\"\n```\n\n资料来源：[packages/phoenix-client/README.md]()\n\n### Custom Authentication Headers\n\nFor custom authentication scenarios:\n\n```python\nfrom phoenix.client import Client\n\nclient = Client(\n base_url=\"https://your-phoenix-instance.com\",\n headers={\"Authorization\": \"Bearer your-api-key\"}\n)\n```\n\n## Architecture\n\n### Client Structure\n\nThe SDK follows a resource-based architecture where the main `Client` provides access to specialized resource objects:\n\n```mermaid\ngraph TD\n A[Client] --> B[prompts]\n A --> C[datasets]\n A --> D[experiments]\n A --> E[spans]\n A --> F[annotations]\n \n B --> B1[create, get, list, format]\n C --> C1[create, append, get, list]\n D --> D1[run, track, evaluate]\n E --> E1[query, filter, export]\n F --> F1[add, update, evaluate]\n```\n\n### SDK Package Structure\n\n```\nphoenix/\n└── client/\n ├── client.py # Main Client and AsyncClient classes\n ├── resources/ # Resource implementations\n │ ├── prompts.py\n │ ├── datasets.py\n │ ├── experiments.py\n │ ├── spans.py\n │ └── annotations.py\n └── helpers/\n └── sdk/ # SDK utilities and helpers\n```\n\n资料来源：[packages/phoenix-client/src/phoenix/client/client.py]()\n资料来源：[packages/phoenix-client/src/phoenix/client/resources]()\n\n## Core Resources\n\n### Prompts Resource\n\nManage prompt templates and versions with versioning support:\n\n```python\nfrom phoenix.client import Client\nfrom phoenix.client.types import PromptVersion\n\nclient = Client()\n\ncontent = \"\"\"\nYou're an expert educator in {{ topic }}. Summarize the following article\nin a few concise bullet points that are easy for beginners to understand.\n\n{{ article }}\n\"\"\"\n\nprompt = client.prompts.create(\n name=\"article-bullet-summarizer\",\n version=PromptVersion(\n messages=[{\"role\": \"user\", \"content\": content}],\n model_name=\"gpt-4o-mini\",\n ),\n prompt_description=\"Summarize an article in a few bullet points\"\n)\n\n# Retrieve and use prompts\nprompt = client.prompts.get(prompt_identifier=\"article-bullet-summarizer\")\n\n# Format the prompt with variables\nprompt_vars = {\n \"topic\": \"Sports\",\n \"article\": \"Moises Henriques has signed to play for Surrey...\"\n}\nformatted_prompt = prompt.format(variables=prompt_vars)\n```\n\n**Prompt Version Type:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `messages` | `List[dict]` | Message array with role and content |\n| `model_name` | `str` | LLM model to use for the prompt |\n| ` temperature` | `float` | Sampling temperature (optional) |\n\n资料来源：[packages/phoenix-client/README.md]()\n\n### Datasets Resource\n\nCreate and manage datasets from various data sources:\n\n```python\nfrom phoenix.client import Client\nimport pandas as pd\n\nclient = Client()\n\n# Create from DataFrame\ndataset = client.datasets.create(\n name=\"my-dataset\",\n dataframe=df,\n description=\"Training data for sentiment analysis\"\n)\n\n# Append additional data\nclient.datasets.append(\n dataset_id=dataset.id,\n dataframe=additional_df\n)\n\n# Get dataset\ndataset = client.datasets.get(\n dataset_name=\"my-dataset\",\n version_id=\"optional-version-id\"\n)\n```\n\n**Supported Input Formats:**\n\n| Format | Method | Example |\n|--------|--------|---------|\n| DataFrame | `dataframe` parameter | `dataframe=pd.DataFrame(...)` |\n| CSV | `csv_path` parameter | `csv_path=\"/path/to/data.csv\"` |\n| Dictionary | `dictionary` parameter | `dictionary=[{\"col\": \"value\"}]` |\n\n资料来源：[packages/phoenix-client/README.md]()\n\n### Experiments Resource\n\nRun evaluations and track experiment results:\n\n```python\nfrom phoenix.client import Client\n\nclient = Client()\n\n# Run an experiment\nexperiment = client.experiments.run(\n name=\"sentiment-analysis-v1\",\n dataset_id=\"dataset-uuid\",\n evaluator_config={\n \"model\": \"gpt-4\",\n \"metrics\": [\"accuracy\", \"f1\"]\n }\n)\n\n# Track results\nclient.experiments.track(\n experiment_id=experiment.id,\n results={\"accuracy\": 0.95, \"f1\": 0.93}\n)\n```\n\n资料来源：[packages/phoenix-client/README.md]()\n\n### Spans Resource\n\nQuery and analyze traces with powerful filtering:\n\n```python\nfrom phoenix.client import Client\n\nclient = Client()\n\n# Query spans with filters\nspans = client.spans.query(\n project_name=\"my-project\",\n filter_conditions={\n \"trace_id\": \"optional-trace-id\",\n \"start_time\": \"2024-01-01T00:00:00Z\",\n \"end_time\": \"2024-01-02T00:00:00Z\"\n },\n limit=100\n)\n\n# Get span details\nspan = client.spans.get(span_id=\"span-uuid\")\n```\n\n**Query Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `project_name` | `str` | Phoenix project name |\n| `filter_conditions` | `dict` | Filtering conditions |\n| `limit` | `int` | Maximum results to return |\n| `start_time` | `datetime` | Start of time range |\n| `end_time` | `datetime` | End of time range |\n\n资料来源：[packages/phoenix-client/src/phoenix/client/resources]()\n\n### Annotations Resource\n\nAdd human feedback and automated evaluations:\n\n```python\nfrom phoenix.client import Client\n\nclient = Client()\n\n# Add annotation to span\nannotation = client.annotations.add(\n span_id=\"span-uuid\",\n label=\"correct\",\n score=1.0,\n metadata={\"reviewer\": \"human\"}\n)\n\n# Bulk add annotations\nclient.annotations.bulk_add(\n annotations=[\n {\"span_id\": \"span-1\", \"label\": \"correct\", \"score\": 1.0},\n {\"span_id\": \"span-2\", \"label\": \"incorrect\", \"score\": 0.0}\n ]\n)\n```\n\n资料来源：[packages/phoenix-client/README.md]()\n\n## Migration from Legacy Client\n\nThe legacy `phoenix.session.client.Client` has been removed. Users must migrate to the new SDK:\n\n```python\n# Old (deprecated)\nfrom phoenix.session.client import Client\n\n# New\nfrom phoenix.client import Client\n```\n\n资料来源：[src/phoenix/__init__.py]()\n\n## Data Flow Diagram\n\n```mermaid\ngraph LR\n A[Python Application] -->|arize-phoenix-client| B[Phoenix REST API]\n B --> C[Phoenix Server]\n C --> D[(Database)]\n \n A --> E[Prompts]\n A --> F[Datasets]\n A --> G[Experiments]\n A --> H[Traces/Spans]\n A --> I[Annotations]\n \n E --> B\n F --> B\n G --> B\n H --> B\n I --> B\n```\n\n## Use Cases\n\n### RAG Evaluation Workflow\n\n```python\nfrom phoenix.client import Client\n\nclient = Client()\n\n# 1. Create dataset\ndataset = client.datasets.create(\n name=\"rag-evaluation-set\",\n dataframe=evaluation_df\n)\n\n# 2. Run evaluation experiment\nexperiment = client.experiments.run(\n name=\"rag-faithfulness-eval\",\n dataset_id=dataset.id,\n evaluator_config={\n \"model\": \"gpt-4\",\n \"metrics\": [\"faithfulness\", \"answer_relevance\"]\n }\n)\n\n# 3. Query results\nresults = client.experiments.get_results(experiment_id=experiment.id)\n\n# 4. Add annotations to spans\nfor span_id, score in results.items():\n client.annotations.add(\n span_id=span_id,\n label=\"faithful\" if score > 0.8 else \"unfaithful\",\n score=score\n )\n```\n\n### Prompt Versioning and Management\n\n```python\nfrom phoenix.client import Client\nfrom phoenix.client.types import PromptVersion\n\nclient = Client()\n\n# Create initial prompt version\nprompt_v1 = client.prompts.create(\n name=\"customer-support-assistant\",\n version=PromptVersion(\n messages=[{\"role\": \"system\", \"content\": \"You are a helpful assistant.\"}],\n model_name=\"gpt-4\"\n )\n)\n\n# Create new version\nprompt_v2 = client.prompts.create(\n name=\"customer-support-assistant\",\n version=PromptVersion(\n messages=[{\"role\": \"system\", \"content\": \"You are a helpful support agent trained to be concise.\"}],\n model_name=\"gpt-4\"\n )\n)\n\n# Compare versions\ncurrent = client.prompts.get(prompt_identifier=\"customer-support-assistant\")\n```\n\n## Summary\n\nThe `arize-phoenix-client` Python SDK provides a comprehensive, Pythonic interface for interacting with the Phoenix observability platform. Key capabilities include:\n\n- **Unified Client Interface** - Single entry point for all Phoenix operations\n- **Resource-Based Design** - Organized access to prompts, datasets, experiments, spans, and annotations\n- **Environment-Based Configuration** - Zero-config setup via environment variables\n- **Async Support** - Built-in async client for asynchronous applications\n- **Type Safety** - Full type hints and Pydantic models for validation\n\n资料来源：[packages/phoenix-client/src/phoenix/client/client.py]()\n资料来源：[packages/phoenix-client/README.md]()\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Arize-ai/phoenix\n\n摘要：发现 38 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Docs proposal: RAG failure mode checklist for observability and eval workflows。\n\n## 1. 安装坑 · 来源证据：Docs proposal: RAG failure mode checklist for observability and eval workflows\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docs proposal: RAG failure mode checklist for observability and eval workflows\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_43a673bd0a9947d3a8758a608e7a5a15 | https://github.com/Arize-ai/phoenix/issues/11472 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：[BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47.0.0 incompatible with App…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47.0.0 incompatible with Apple Hypervisor VM\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_beadd6130d804f29b2f261a0194d2262 | https://github.com/Arize-ai/phoenix/issues/12941 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：[agents] investigate clientside tracing for external tools\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[agents] investigate clientside tracing for external tools\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2e2fc634da044ed9a177a6dd85a78b23 | https://github.com/Arize-ai/phoenix/issues/13173 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 失败模式：installation: [BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47.0.0 incompatible with Apple Hypervisor VM\n- 对用户的影响：Developers may fail before the first successful local run: [BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47.0.0 incompatible with Apple Hypervisor VM\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47.0.0 incompatible with Apple Hypervisor VM. Context: Observed when using python, docker, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_b3db5f930ac5e7b7f85e47ff9693c190 | https://github.com/Arize-ai/phoenix/issues/12941 | [BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47.0.0 incompatible with Apple Hypervisor VM\n\n## 5. 配置坑 · 失败模式：configuration: [sandboxes] per-execute timeout enforcement is incomplete across backends\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: [sandboxes] per-execute timeout enforcement is incomplete across backends\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [sandboxes] per-execute timeout enforcement is incomplete across backends\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [sandboxes] per-execute timeout enforcement is incomplete across backends. Context: Observed when using python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_5978fbc9db2aea6762b2ab2f9e8d0205 | https://github.com/Arize-ai/phoenix/issues/13313 | [sandboxes] per-execute timeout enforcement is incomplete across backends\n\n## 6. 配置坑 · 来源证据：[sandboxes] per-execute timeout enforcement is incomplete across backends\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[sandboxes] per-execute timeout enforcement is incomplete across backends\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7e0ad954523449959675c0433a0ff80b | https://github.com/Arize-ai/phoenix/issues/13313 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:564072810 | https://github.com/Arize-ai/phoenix | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 失败模式：runtime: arize-phoenix: v15.5.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: arize-phoenix: v15.5.0\n- 对用户的影响：Upgrade or migration may change expected behavior: arize-phoenix: v15.5.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: arize-phoenix: v15.5.0. Context: Observed when using docker\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_77bc9f7097156e71a699d05abced2916 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.0 | arize-phoenix: v15.5.0\n\n## 9. 运行坑 · 来源证据：arize-phoenix: v15.3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.3.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d364a0a28a14428baff5ca692cb00578 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.3.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 运行坑 · 来源证据：arize-phoenix: v15.5.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.5.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ad2696a72e314b52b79d157bf261f7bd | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 运行坑 · 来源证据：arize-phoenix: v15.5.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.5.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b75368026b414d1bbe31d7d3e90b2731 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 运行坑 · 来源证据：arize-phoenix: v15.6.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.6.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_49d41c4c92f24db2b382ebd014f9bd14 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.6.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 运行坑 · 来源证据：arize-phoenix: v15.7.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.7.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_826b7f8e0d2342cabfedab3cabb1a2dc | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.7.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 运行坑 · 来源证据：arize-phoenix: v15.9.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.9.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0d47708aa40b4b99b3f132751181cf43 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.9.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 维护坑 · 失败模式：migration: [agents] investigate clientside tracing for external tools\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: [agents] investigate clientside tracing for external tools\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [agents] investigate clientside tracing for external tools\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [agents] investigate clientside tracing for external tools. Context: Observed when using python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_f8117a9bb9f5654b2e4f54cc2b4f7fe3 | https://github.com/Arize-ai/phoenix/issues/13173 | [agents] investigate clientside tracing for external tools\n\n## 16. 维护坑 · 来源证据：[BUG]: playground experiment UI rendering issue\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[BUG]: playground experiment UI rendering issue\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_610a50542f75479b953fd6a15a55776f | https://github.com/Arize-ai/phoenix/issues/13308 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 17. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | last_activity_observed missing\n\n## 18. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:564072810 | https://github.com/Arize-ai/phoenix | no_demo; severity=medium\n\n## 19. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:564072810 | https://github.com/Arize-ai/phoenix | no_demo; severity=medium\n\n## 20. 安全/权限坑 · 来源证据：GenerativeModelStore: _last_fetch_id can regress and defeat incremental fetch\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：GenerativeModelStore: _last_fetch_id can regress and defeat incremental fetch\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_547816d87273465a88a09397fc2c4ab1 | https://github.com/Arize-ai/phoenix/issues/13241 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：[security] setup deepsec\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[security] setup deepsec\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_153e6ddc8487493e893542da4c348bbe | https://github.com/Arize-ai/phoenix/issues/13275 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 22. 安全/权限坑 · 来源证据：arize-phoenix: v15.10.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.10.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1ce89c62b10a43288f4c6394276bc97c | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.10.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 23. 安全/权限坑 · 来源证据：arize-phoenix: v15.4.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.4.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fea401ed7b774dc7885c245774e87cce | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.4.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 24. 安全/权限坑 · 来源证据：arize-phoenix: v15.8.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.8.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2ecb08e3e7e04b60ac87fab18439546d | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.8.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 25. 能力坑 · 失败模式：capability: [BUG]: playground experiment UI rendering issue\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: [BUG]: playground experiment UI rendering issue\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [BUG]: playground experiment UI rendering issue\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG]: playground experiment UI rendering issue. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_3c24e5ce6d42a5e1a0e0230aecb92e81 | https://github.com/Arize-ai/phoenix/issues/13308 | [BUG]: playground experiment UI rendering issue\n\n## 26. 能力坑 · 失败模式：capability: [security] setup deepsec\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: [security] setup deepsec\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [security] setup deepsec\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [security] setup deepsec. Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_d37b8a28ea2b1ff0c52a5ae60c624e97 | https://github.com/Arize-ai/phoenix/issues/13275 | [security] setup deepsec\n\n## 27. 能力坑 · 失败模式：conceptual: Docs proposal: RAG failure mode checklist for observability and eval workflows\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this conceptual risk before relying on the project: Docs proposal: RAG failure mode checklist for observability and eval workflows\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Docs proposal: RAG failure mode checklist for observability and eval workflows\n- 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_6c4658bbeb1e5baa04ed96cfad5079aa | https://github.com/Arize-ai/phoenix/issues/11472 | Docs proposal: RAG failure mode checklist for observability and eval workflows\n\n## 28. 运行坑 · 失败模式：performance: GenerativeModelStore: _last_fetch_id can regress and defeat incremental fetch\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this performance risk before relying on the project: GenerativeModelStore: _last_fetch_id can regress and defeat incremental fetch\n- 对用户的影响：Developers may hit a documented source-backed failure mode: GenerativeModelStore: _last_fetch_id can regress and defeat incremental fetch\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: GenerativeModelStore: _last_fetch_id can regress and defeat incremental fetch. Context: Observed when using python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_23b7285d4fadfe700afa410a8950e461 | https://github.com/Arize-ai/phoenix/issues/13241 | GenerativeModelStore: _last_fetch_id can regress and defeat incremental fetch\n\n## 29. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | issue_or_pr_quality=unknown\n\n## 30. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | release_recency=unknown\n\n## 31. 维护坑 · 失败模式：maintenance: arize-phoenix: v15.10.0\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: arize-phoenix: v15.10.0\n- 对用户的影响：Upgrade or migration may change expected behavior: arize-phoenix: v15.10.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: arize-phoenix: v15.10.0. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_e4788bb4f329f5cc3023bb09f9cd7813 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.10.0 | arize-phoenix: v15.10.0\n\n## 32. 维护坑 · 失败模式：maintenance: arize-phoenix: v15.10.1\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: arize-phoenix: v15.10.1\n- 对用户的影响：Upgrade or migration may change expected behavior: arize-phoenix: v15.10.1\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: arize-phoenix: v15.10.1. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_8400f06faab947c42c1ebe0b7884772b | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.10.1 | arize-phoenix: v15.10.1\n\n## 33. 维护坑 · 失败模式：maintenance: arize-phoenix: v15.4.0\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: arize-phoenix: v15.4.0\n- 对用户的影响：Upgrade or migration may change expected behavior: arize-phoenix: v15.4.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: arize-phoenix: v15.4.0. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_653c077d0085ffa005a084fd3ca970fa | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.4.0 | arize-phoenix: v15.4.0\n\n## 34. 维护坑 · 失败模式：maintenance: arize-phoenix: v15.5.1\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: arize-phoenix: v15.5.1\n- 对用户的影响：Upgrade or migration may change expected behavior: arize-phoenix: v15.5.1\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: arize-phoenix: v15.5.1. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_bc2b79f0aa2ad5b7394adb522e327c95 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.1 | arize-phoenix: v15.5.1\n\n## 35. 维护坑 · 失败模式：maintenance: arize-phoenix: v15.6.0\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: arize-phoenix: v15.6.0\n- 对用户的影响：Upgrade or migration may change expected behavior: arize-phoenix: v15.6.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: arize-phoenix: v15.6.0. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_362d0c49630790947fb31ce598711670 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.6.0 | arize-phoenix: v15.6.0\n\n## 36. 维护坑 · 失败模式：maintenance: arize-phoenix: v15.7.0\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: arize-phoenix: v15.7.0\n- 对用户的影响：Upgrade or migration may change expected behavior: arize-phoenix: v15.7.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: arize-phoenix: v15.7.0. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_cf7af51ba96b7aae5b7f6e9fe76d3a80 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.7.0 | arize-phoenix: v15.7.0\n\n## 37. 维护坑 · 失败模式：maintenance: arize-phoenix: v15.8.0\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: arize-phoenix: v15.8.0\n- 对用户的影响：Upgrade or migration may change expected behavior: arize-phoenix: v15.8.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: arize-phoenix: v15.8.0. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_cb667f7181256aff35598629d537411d | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.8.0 | arize-phoenix: v15.8.0\n\n## 38. 维护坑 · 失败模式：maintenance: arize-phoenix: v15.9.0\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: arize-phoenix: v15.9.0\n- 对用户的影响：Upgrade or migration may change expected behavior: arize-phoenix: v15.9.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: arize-phoenix: v15.9.0. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_3f5a219a80efa7ef7afa6caf0db5a21c | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.9.0 | arize-phoenix: v15.9.0\n\n\n",
"markdown_key": "phoenix",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:564072810",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/Arize-ai/phoenix"
},
{
"evidence_id": "art_141f599975834bcfbe3734e8a46fc205",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/Arize-ai/phoenix#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "phoenix 说明书",
"toc": [
"https://github.com/Arize-ai/phoenix 项目说明书",
"目录",
"Project Overview",
"What is Phoenix?",
"Architecture Overview",
"JavaScript/TypeScript Packages",
"Python SDK",
"Configure Phoenix tracing",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "a3299461accfcdf66bf983d95bc2cf0bd3229170",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"Dockerfile",
"README.md",
"docker-compose.yml",
"uv.lock",
"docs/PROMPT.md",
"docs/openapi.json",
"docs/phoenix.mdx",
"docs/analytics.js",
"docs/phoenix/phoenix-cloud.mdx",
"docs/phoenix/sdk-api-reference.mdx",
"docs/phoenix/self-hosting.mdx",
"docs/phoenix/get-started.mdx",
"docs/phoenix/integrations.mdx",
"docs/phoenix/agent-assisted-setup.mdx",
"docs/phoenix/user-guide.mdx",
"docs/phoenix/release-notes.mdx",
"docs/phoenix/end-to-end-features-notebook.mdx",
"docs/phoenix/cookbook.mdx",
"docs/phoenix/skill.md",
"docs/phoenix/quickstart.mdx",
"docs/phoenix/production-guide.mdx",
"docs/phoenix/environments.mdx",
"docs/phoenix/phoenix-demo.mdx",
"docs/phoenix/prompt-engineering/concepts-prompts.mdx",
"docs/phoenix/prompt-engineering/how-to-prompts.mdx",
"docs/phoenix/prompt-engineering/overview-prompts.mdx",
"docs/phoenix/prompt-engineering/tutorial.mdx",
"docs/phoenix/cookbook/agent-workflow-patterns.mdx",
"docs/phoenix/settings/api-keys.mdx",
"docs/phoenix/settings/custom-ai-providers.mdx",
"docs/phoenix/settings/secrets.mdx",
"docs/phoenix/settings/data-retention.mdx",
"docs/phoenix/settings/access-control-rbac.mdx",
"docs/phoenix/documentation/jp.mdx",
"docs/phoenix/documentation/zh.mdx",
"docs/phoenix/tracing/how-to-tracing.mdx",
"docs/phoenix/tracing/llm-traces.mdx",
"docs/phoenix/tracing/features-tracing.mdx",
"docs/phoenix/tracing/tutorial.mdx"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# phoenix-ui - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 phoenix-ui 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.agents/skills/agent-browser/SKILL.md`, `.agents/skills/mintlify/SKILL.md`, `.agents/skills/phoenix-cli/SKILL.md`, `.agents/skills/phoenix-design/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.agents/skills/agent-browser/SKILL.md`, `.agents/skills/mintlify/SKILL.md`, `.agents/skills/phoenix-cli/SKILL.md`, `.agents/skills/phoenix-design/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `js/examples/apps/langchain-quickstart/README.md`, `packages/phoenix-client/README.md`, `packages/phoenix-evals/README.md` 等 Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `pip install arize-phoenix` 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0010` supported 0.86\n- `pip install arize-phoenix-client` 证据：`packages/phoenix-client/README.md` Claim：`clm_0006` supported 0.86\n- `pip install 'arize-phoenix-evals>=2.0.0' openai` 证据：`packages/phoenix-evals/README.md` Claim：`clm_0007` supported 0.86\n- `pip install -r requirements.txt` 证据：`packages/phoenix-otel/docs/README.md` Claim：`clm_0008` supported 0.86\n- `pip install -e .. # Install phoenix-otel package in development mode` 证据：`packages/phoenix-otel/docs/README.md` Claim：`clm_0009` supported 0.86\n- `pip install arize-phoenix-otel` 证据：`packages/phoenix-otel/README.md` Claim：`clm_0010` supported 0.86\n- `pip install openinference-instrumentation-openai` 证据：`packages/phoenix-otel/README.md` Claim：`clm_0011` supported 0.86\n- `pip install openinference-instrumentation-langchain # For LangChain` 证据：`packages/phoenix-otel/README.md` Claim：`clm_0012` supported 0.86\n- `pip install openinference-instrumentation-llama-index # For LlamaIndex` 证据：`packages/phoenix-otel/README.md` Claim：`clm_0013` supported 0.86\n- `npx skills add Arize-ai/phoenix --skill phoenix-tracing` 证据：`packages/phoenix-otel/README.md` Claim：`clm_0014` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.agents/skills/agent-browser/SKILL.md`, `.agents/skills/mintlify/SKILL.md`, `.agents/skills/phoenix-cli/SKILL.md`, `.agents/skills/phoenix-design/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.agents/skills/agent-browser/SKILL.md`, `.agents/skills/mintlify/SKILL.md`, `.agents/skills/phoenix-cli/SKILL.md`, `.agents/skills/phoenix-design/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `js/examples/apps/langchain-quickstart/README.md`, `packages/phoenix-client/README.md`, `packages/phoenix-evals/README.md` 等 Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0010` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.agents/skills/agent-browser/SKILL.md`, `.agents/skills/mintlify/SKILL.md`, `.agents/skills/phoenix-cli/SKILL.md`, `.agents/skills/phoenix-design/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `js/examples/apps/langchain-quickstart/README.md`, `packages/phoenix-client/README.md`, `packages/phoenix-evals/README.md` 等\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.agents/skills/agent-browser/SKILL.md`, `.agents/skills/mintlify/SKILL.md`, `.agents/skills/phoenix-cli/SKILL.md`, `.agents/skills/phoenix-design/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `js/examples/apps/langchain-quickstart/README.md`, `packages/phoenix-client/README.md`, `packages/phoenix-evals/README.md` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0016` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `js/examples/apps/langchain-quickstart/README.md`, `packages/phoenix-client/README.md`, `packages/phoenix-evals/README.md` 等 Claim：`clm_0017` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.agents/skills/agent-browser/SKILL.md`, `.agents/skills/mintlify/SKILL.md`, `.agents/skills/phoenix-cli/SKILL.md`, `.agents/skills/phoenix-design/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `js/examples/apps/langchain-quickstart/README.md`, `packages/phoenix-client/README.md`, `packages/phoenix-evals/README.md` 等 Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：5137\n- 重要文件覆盖：40/5137\n- 证据索引条目：107\n- 角色 / Skill 条目：29\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 phoenix-ui 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 phoenix-ui 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 phoenix-ui 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 29 个角色 / Skill / 项目文档条目。\n\n- **agent-browser**（skill）：Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to \"open a website\", \"fill out a form\", \"click a button\", \"take a screenshot\", \"scrape data from a page\", \"test this web app\", \"login to a site\", \"automate… 激活提示：当用户任务与“agent-browser”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/agent-browser/SKILL.md`\n- **mintlify**（skill）：Build and maintain documentation sites with Mintlify. Use when 激活提示：当用户任务与“mintlify”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/mintlify/SKILL.md`\n- **phoenix-cli**（skill）：Debug LLM applications using the Phoenix CLI. Fetch traces, analyze errors, structure trace review with open coding and axial coding, inspect datasets, review experiments, query annotation configs, and use the GraphQL API. Use whenever the user is analyzing traces or spans, investigating LLM/agent failures, deciding what to do after instrumenting an app, building failure taxonomies, choosing what evals to write, or… 激活提示：当用户任务与“phoenix-cli”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-cli/SKILL.md`\n- **phoenix-design**（skill）：Design system conventions for the Phoenix frontend — layout, dialogs, error display, BEM CSS class naming, and CSS design tokens. Use when building UI, naming CSS classes, creating or consuming tokens, handling errors, or designing dialog interactions in app/src/. 激活提示：当用户任务与“phoenix-design”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-design/SKILL.md`\n- **phoenix-docs-gap-audit**（skill）： 激活提示：当用户任务与“phoenix-docs-gap-audit”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-docs-gap-audit/SKILL.md`\n- **phoenix-evals-new-metric**（skill）：- 激活提示：当用户任务与“phoenix-evals-new-metric”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-evals-new-metric/SKILL.md`\n- **phoenix-evals**（skill）：Build and run evaluators for AI/LLM applications using Phoenix. 激活提示：当用户任务与“phoenix-evals”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-evals/SKILL.md`\n- **phoenix-frontend**（skill）：Frontend development guidelines for the Phoenix AI observability platform. Use when writing, reviewing, or modifying React components, TypeScript code, styles, or UI features in the app/ directory. Triggers on any frontend task — new components, UI changes, styling, accessibility fixes, form handling, or component refactoring. Also use when the user asks about frontend conventions or component patterns for this proj… 激活提示：当用户任务与“phoenix-frontend”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-frontend/SKILL.md`\n- **phoenix-github**（skill）：Manage GitHub issues, labels, and project boards for the Arize-ai/phoenix repository. Use when filing roadmap issues, triaging bugs, applying labels, managing the Phoenix roadmap project board, or querying issue/project state via the GitHub CLI. 激活提示：当用户任务与“phoenix-github”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-github/SKILL.md`\n- **phoenix-integration-snippets**（skill）： 激活提示：当用户任务与“phoenix-integration-snippets”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-integration-snippets/SKILL.md`\n- **phoenix-llms-txt**（skill）： 激活提示：当用户任务与“phoenix-llms-txt”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-llms-txt/SKILL.md`\n- **phoenix-playwright-tests**（skill）：Write Playwright E2E tests for the Phoenix AI observability platform. Use when creating, updating, or debugging Playwright tests, or when the user asks about testing UI features, writing E2E tests, or automating browser interactions for Phoenix. 激活提示：当用户任务与“phoenix-playwright-tests”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-playwright-tests/SKILL.md`\n- **phoenix-pr-screenshot**（skill）：Screenshot a running Phoenix feature and attach images to a GitHub PR. Builds the frontend, starts Phoenix with env vars, uses agent-browser to capture screenshots, uploads to GCS, and updates the PR body. 激活提示：当用户任务与“phoenix-pr-screenshot”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-pr-screenshot/SKILL.md`\n- **phoenix-pxi-playwright**（skill）：Write, extend, and debug PXI Playwright E2E tests for Phoenix. Use when adding PXI agent frontend specs, authoring LLM-as-judge rubrics, asserting PXI tool use, persisting PXI test runs as Phoenix experiments, or debugging PXI E2E failures. 激活提示：当用户任务与“phoenix-pxi-playwright”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-pxi-playwright/SKILL.md`\n- **phoenix-pxi**（skill）：Development guide for the Phoenix PXI agent. Use when modifying PXI-specific frontend or backend behavior, extending PXI tool wiring, updating PXI runtime capabilities, or changing the PXI agent request/dispatch flow. Start here for PXI-specific workflows, then read the relevant resource file for the layer you are changing. 激活提示：当用户任务与“phoenix-pxi”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-pxi/SKILL.md`\n- **phoenix-release-notes**（skill）： 激活提示：当用户任务与“phoenix-release-notes”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-release-notes/SKILL.md`\n- **phoenix-release-please**（skill）： 激活提示：当用户任务与“phoenix-release-please”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-release-please/SKILL.md`\n- **phoenix-rest-api**（skill）： 激活提示：当用户任务与“phoenix-rest-api”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-rest-api/SKILL.md`\n- **phoenix-server**（skill）： 激活提示：当用户任务与“phoenix-server”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-server/SKILL.md`\n- **phoenix-skills-audit**（skill）： 激活提示：当用户任务与“phoenix-skills-audit”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-skills-audit/SKILL.md`\n- **phoenix-tracing**（skill）：OpenInference semantic conventions and instrumentation for Phoenix AI observability. Use when implementing LLM tracing, creating custom spans, or deploying to production. 激活提示：当用户任务与“phoenix-tracing”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-tracing/SKILL.md`\n- **phoenix-typescript-package-docs**（skill）： 激活提示：当用户任务与“phoenix-typescript-package-docs”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-typescript-package-docs/SKILL.md`\n- **phoenix-typescript**（skill）：TypeScript conventions and patterns for any TypeScript code in the Phoenix monorepo — including js/packages/, app/, and any other TS directories. Use this skill whenever writing, reviewing, or modifying TypeScript code — new functions, types, exports, tests, or refactors. Also trigger when the user asks about TS patterns, naming conventions, or best practices for this project. 激活提示：当用户任务与“phoenix-typescript”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-typescript/SKILL.md`\n- **typescript-tooling-migration**（skill）：Migrate or upgrade TypeScript tooling in the Phoenix monorepo. Use when upgrading TypeScript versions, switching tools ESLint to oxlint, Prettier to oxfmt , upgrading bundlers Vite, esbuild , or making major dependency upgrades. Triggers on requests to migrate, upgrade, or replace TypeScript/JavaScript tooling. 激活提示：当用户任务与“typescript-tooling-migration”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/typescript-tooling-migration/SKILL.md`\n- **vercel-react-best-practices**（skill）：React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements. 激活提示：当用户任务与“vercel-react-best-practices”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/vercel-react-best-practices/SKILL.md`\n- **arize-phoenix**（skill）：Open-source AI observability platform for tracing, evaluating, and improving LLM applications with OpenTelemetry integration 激活提示：当用户任务与“arize-phoenix”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`docs/phoenix/skill.md`\n- **phoenix-cli-development**（skill）： 激活提示：当用户任务与“phoenix-cli-development”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`js/packages/phoenix-cli/.agents/skills/phoenix-cli-development/SKILL.md`\n- **phoenix-client-development**（skill）： 激活提示：当用户任务与“phoenix-client-development”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`js/packages/phoenix-client/.agents/skills/phoenix-client-development/SKILL.md`\n- **phoenix-otel-development**（skill）： 激活提示：当用户任务与“phoenix-otel-development”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`js/packages/phoenix-otel/.agents/skills/phoenix-otel-development/SKILL.md`\n\n## 证据索引\n\n- 共索引 107 条证据。\n\n- **Phoenix OTEL Documentation**（documentation）：This directory contains the Sphinx documentation for the arize-phoenix-otel package. 证据：`packages/phoenix-otel/docs/README.md`\n- **Arize Phoenix**（skill_instruction）：Phoenix is an open-source AI observability platform built on OpenTelemetry that helps developers understand, debug, and improve AI applications. It provides comprehensive tracing, evaluation, prompt engineering, and experimentation capabilities for LLM-based systems. Phoenix captures detailed execution information from AI applications, measures output quality with evaluators, enables systematic prompt iteration, and supports data-driven experimentation to optimize AI performance. 证据：`docs/phoenix/skill.md`\n- **Agent Instructions**（documentation）：This repo uses a Makefile for all build, test, lint, and dev commands. Run make help to see all available targets. 证据：`AGENTS.md`\n- **Installation**（documentation）：Phoenix is an open-source AI observability platform designed for experimentation, evaluation, and troubleshooting. It provides: 证据：`README.md`\n- **Maintenance README for Phoenix Sphinx API Documentation**（documentation）：Maintenance README for Phoenix Sphinx API Documentation 证据：`api_reference/README.md`\n- **Arize Phoenix App**（documentation）：The Phoenix application is a web application built to enable rapid troubleshooting and EDA of model inferences and LLM applications. It is hosted by the Phoenix server and consumes the GraphQL API served by the Python runtime. 证据：`app/README.md`\n- **Phoenix Examples**（documentation）：A collection of examples demonstrating how to use Phoenix. 证据：`examples/README.md`\n- **phoenix-helm**（documentation）：! Version: 7.0.9 https://img.shields.io/badge/Version-7.0.9-informational?style=flat-square ! Type: application https://img.shields.io/badge/Type-application-informational?style=flat-square ! AppVersion: 15.9.0 https://img.shields.io/badge/AppVersion-15.9.0-informational?style=flat-square 证据：`helm/README.md`\n- **Internal Documentation**（documentation）：This folder contains materials that are only relevant to core maintainers of this project. 证据：`internal_docs/README.md`\n- **Readme**（documentation）：Official TypeScript libraries for interacting with a running Arize Phoenix https://github.com/Arize-ai/phoenix instance. 证据：`js/README.MD`\n- **Readme**（documentation）：This directory contains a set of manifests and overlays that describe our various Kubernetes deployment options. These deployments can be invoked from the repository root. 证据：`kustomize/README.md`\n- **Phoenix Scripts**（documentation）：Utility, testing, data-generation, and CI scripts that support Phoenix development. Most Python scripts can be run with uv run scripts/ ; some declare PEP 723 inline dependencies and others assume the project venv is active. 证据：`scripts/README.md`\n- **Phoenix Coding Agent Skills**（documentation）：This directory contains skills https://docs.anthropic.com/en/docs/claude-code/skills that teach coding agents how to work with Phoenix. They can be used with Claude Code, Cursor, and other compatible tools. 证据：`.agents/skills/README.md`\n- **Phoenix Tracing Skill**（documentation）：OpenInference semantic conventions and instrumentation guides for Phoenix. 证据：`.agents/skills/phoenix-tracing/README.md`\n- **React Best Practices**（documentation）：Version 1.0.0 Vercel Engineering January 2026 证据：`.agents/skills/vercel-react-best-practices/AGENTS.md`\n- **agent-framework-analysis**（documentation）：This project shows the same agent defined in multiple different frameworks: - Pure Code aka no framework - LangGraph - LlamaIndex Workflows 证据：`examples/agent_framework_comparison/README.md`\n- **Agents**（documentation）：Example agent implementations instrumented with OpenInference https://github.com/Arize-ai/openinference and traced to Phoenix https://github.com/Arize-ai/phoenix . Each example runs benchmark tasks through an agent framework, producing rich traces with LLM calls, tool executions, and multi-turn conversation flows. 证据：`examples/agents/README.md`\n- **tau-bench + LangGraph**（documentation）：A customer service agent built with LangGraph, instrumented with OpenInference, running tau-bench retail domain tasks. This is the LangGraph counterpart to the OpenAI Agents SDK implementation ../tau bench openai agents/README.md — same tools, same database, same simulated user, different framework. Comparing traces between the two reveals how framework choice affects what trajectory information is available. 证据：`examples/agents/tau_bench_langgraph/README.md`\n- **tau-bench + OpenAI Agents SDK**（documentation）：A customer service agent built with the OpenAI Agents SDK, instrumented with OpenInference, running tau-bench retail domain tasks. This is part of the trajectory evaluation investigation — examining what OTel traces capture when an agent framework naturally handles tool-calling conversations. 证据：`examples/agents/tau_bench_openai_agents/README.md`\n- **TRAJECT-Bench + LangGraph**（documentation）：A single-turn tool-calling agent built with LangGraph, instrumented with OpenInference, running TRAJECT-Bench https://huggingface.co/datasets/Jnnamchi/traject-bench tasks. This contrasts with the tau-bench examples on every dimension: single-turn not multi-turn , mock tools not live DB mutations , parallel and sequential tool patterns not conversational . 证据：`examples/agents/traject_bench_langgraph/README.md`\n- **Code Generation Agent Example**（documentation）：This folder contains examples for building a Code Generation Code-Gen agent using the LangChain library. This agent is designed to generate, refine, and validate code using OpenAI models. 证据：`examples/code_gen_agent/README.md`\n- **Computer Use Agent Examples**（documentation）：This repository contains examples for building a Computer Use Operator Agent using LangGraph and Anthropic . The agent leverages Anthropic's beta APIs to perform various computer-related tasks, including executing Bash commands, editing files, and performing system operations. 证据：`examples/computer_use_agent/README.md`\n- **Running Evals with Cron**（documentation）：This example demonstrates how to compute and upload evals on a regular schedule using cron . 证据：`examples/cron-evals/README.md`\n- **Llama Researcher**（documentation）：In this tutorial, we'll create LLama-Researcher using LlamaIndex workflows, inspired by GPT-Researcher. https://github.com/assafelovic/gpt-researcher 证据：`examples/llamaindex-workflows-research-agent/README.md`\n- **Agentic RAG Examples**（documentation）：This folder contains examples for building a Retrieval-Augmented Generation RAG agent using the LangChain library. 证据：`examples/rag_agent/README.md`\n- **Deploying Phoenix with a Reverse Proxy**（documentation）：Deploying Phoenix with a Reverse Proxy 证据：`examples/reverse-proxy/README.md`\n- **LDAP Authentication - Appendices**（documentation）：Detailed technical references for the LDAP Authentication specification ../ldap-authentication.md . 证据：`internal_docs/specs/ldap-authentication/README.md`\n- **PostgreSQL JSON vs JSONB Demo**（documentation）：This project demonstrates the key differences between PostgreSQL's JSON and JSONB data types. The most striking difference is how they handle key ordering: 证据：`internal_docs/vignettes/json-jsonb-demo/README.md`\n- **OTel contextvars + async generators**（documentation）：OTel contextvars + async generators 证据：`internal_docs/vignettes/otel-contextvars-async/README.md`\n- **PostgreSQL with TLS Setup**（documentation）：This vignette demonstrates how to set up PostgreSQL with TLS encryption. 证据：`internal_docs/vignettes/postgresql_tls/README.md`\n- **SQLAlchemy Polymorphic User Example**（documentation）：SQLAlchemy Polymorphic User Example 证据：`internal_docs/vignettes/sqlalchemy/polymorphic_user/README.md`\n- **Changesets**（documentation）：Hello and welcome! This folder has been automatically generated by @changesets/cli , a build tool that works with multi-package repos, or single-package repos to help you version and publish your code. You can find the full documentation for it in our repository https://github.com/changesets/changesets 证据：`js/.changeset/README.md`\n- **CLI Agent Starter Kit**（documentation）：This is a TypeScript CLI agent starter kit with AI SDK and Anthropic integration. 证据：`js/examples/apps/cli-agent-starter-kit/AGENTS.md`\n- **CLI Agent Starter Kit**（documentation）：A TypeScript CLI agent with AI SDK, Anthropic Claude, and Phoenix observability. Demonstrates a Phoenix documentation assistant with declarative tool architecture. 证据：`js/examples/apps/cli-agent-starter-kit/README.md`\n- **Agent Evaluation Harness**（documentation）：Automated evaluation framework for the Phoenix Documentation Assistant CLI agent. 证据：`js/examples/apps/cli-agent-starter-kit/evals/README.md`\n- **TypeScript Experiments and Evals with Arize Phoenix**（documentation）：TypeScript Experiments and Evals with Arize Phoenix 证据：`js/examples/apps/demo-document-relevancy-experiment/README.md`\n- **TypeScript Experiments Quickstart**（documentation）：This tutorial demonstrates how to run experiments with Phoenix using TypeScript. It shows how to create datasets, define task functions, use code-based and LLM-as-a-Judge evaluators, and compare different versions of an AI agent. 证据：`js/examples/apps/experiments-quickstart/README.md`\n- **LangChain TypeScript Quickstart**（documentation）：A LangChain TypeScript travel planner agent with Phoenix tracing and optional evaluations. 证据：`js/examples/apps/langchain-quickstart/README.md`\n- **Mastra Agent with Arize Phoenix Tracing**（documentation）：Mastra Agent with Arize Phoenix Tracing 证据：`js/examples/apps/mastra-agent/README.md`\n- **Mastra + Phoenix TypeScript Quickstart**（documentation）：Mastra + Phoenix TypeScript Quickstart 证据：`js/examples/apps/mastra-quickstart/README.md`\n- **Phoenix Experiment Runner**（documentation）：This is an example app that uses the phoenix-client and @clack/prompts to run experiments. 证据：`js/examples/apps/phoenix-experiment-runner/README.md`\n- **Phoenix Tracing Tutorial TypeScript**（documentation）：Phoenix Tracing Tutorial TypeScript 证据：`js/examples/apps/tracing-tutorial/README.md`\n- **JavaScript / Deno Notebook Examples**（documentation）：JavaScript / Deno Notebook Examples 证据：`js/examples/notebooks/README.md`\n- **Installation**（documentation）：A command-line interface for Arize Phoenix https://github.com/Arize-ai/phoenix . Fetch traces, inspect datasets, query experiments, and access prompts directly from your terminal—or pipe them into AI coding agents like Claude Code, Cursor, Codex, and Gemini CLI. 证据：`js/packages/phoenix-cli/README.md`\n- **Installation**（documentation）：This package provides a TypeScript client for the Arize Phoenix https://github.com/Arize-ai/phoenix API. It is still under active development and is subject to change. 证据：`js/packages/phoenix-client/README.md`\n- **Running phoenix-client Examples**（documentation）：To run the TypeScript examples in this directory, you need to have tsx installed globally. tsx allows you to run TypeScript files directly without compiling them first. 证据：`js/packages/phoenix-client/examples/README.md`\n- **Installation**（documentation）：Shared configuration parsing utilities used across @arizeai/phoenix-otel and @arizeai/phoenix-client . Provides typed helpers for reading Phoenix environment variables. 证据：`js/packages/phoenix-config/README.md`\n- **Installation**（documentation）：This package provides a TypeScript evaluation library. It is vendor agnostic and can be used in isolation of any framework or platform. This package is still under active development and is subject to change. 证据：`js/packages/phoenix-evals/README.md`\n- **Running phoenix-evals Examples**（documentation）：To run the TypeScript examples in this directory, you need to have tsx installed globally. tsx allows you to run TypeScript files directly without compiling them first. 证据：`js/packages/phoenix-evals/examples/README.md`\n- **Installation**（documentation）：Phoenix MCP Server is an implementation of the Model Context Protocol for the Arize Phoenix platform. It provides a unified interface to Phoenix's capabilities. 证据：`js/packages/phoenix-mcp/README.md`\n- **Features**（documentation）：A lightweight wrapper around OpenTelemetry for Node.js applications that simplifies sending traces to Arize Phoenix https://github.com/Arize-ai/phoenix . @arizeai/phoenix-otel handles provider registration and OTLP export, then re-exports the full @arizeai/openinference-core helper surface from the same package path so you can register tracing and author manual spans from one import. 证据：`js/packages/phoenix-otel/README.md`\n- **Features**（documentation）：arize-phoenix-client Phoenix Client provides an interface for interacting with the Phoenix platform via its REST API, enabling you to manage datasets, run experiments, analyze traces, and collect feedback programmatically. 证据：`packages/phoenix-client/README.md`\n- **arize-phoenix-evals**（documentation）：Phoenix Evals provides lightweight, composable building blocks for writing and running evaluations on LLM applications, including tools to determine relevance, toxicity, hallucination detection, and much more. 证据：`packages/phoenix-evals/README.md`\n- **Features**（documentation）：Provides a lightweight wrapper around OpenTelemetry primitives with Phoenix-aware defaults. Phoenix OTEL also gives you access to tracing decorators for common GenAI patterns. 证据：`packages/phoenix-otel/README.md`\n- **Analytics**（documentation）：Analytics How to Run 证据：`scripts/analytics/README.md`\n- **Phoenix Development Environment**（documentation）：Complete Docker Compose development environment with Phoenix, PostgreSQL, Grafana, Prometheus, and OIDC authentication using Traefik reverse proxy. 证据：`scripts/docker/devops/README.md`\n- **K8s Test Setup for ROLE ATTRIBUTE PATH**（documentation）：K8s Test Setup for ROLE ATTRIBUTE PATH 证据：`scripts/docker/devops/k8s/README.md`\n- **Phoenix OIDC Debug Server**（documentation）：A fully spec-compliant OpenID Connect 1.0 server implementation for testing and debugging authentication flows. This server is designed for development environments and provides comprehensive logging to help understand the OIDC protocol. 证据：`scripts/docker/devops/oidc-server/README.md`\n- **Phoenix SMTP Development Server**（documentation）：A simple SMTP server for visualizing and debugging emails emitted from Phoenix during development. Not for production use. 证据：`scripts/docker/devops/smtp-server/README.md`\n- **Vite Dev Server - Technical Notes**（documentation）：1. Port Conflict Avoidance Problem: Don't want Vite's 5173 exposed on host conflicts, security Solution: Route everything through Traefik on port 18273 - Vite container: expose: \"5173\" internal only, no ports: mapping - Traefik label: traefik.http.services.vite-dev.loadbalancer.server.port=5173 - Client connects to: http://localhost:18273/phoenix/vite/... 证据：`scripts/docker/devops/vite-dev/README.md`\n- 其余 47 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`packages/phoenix-otel/docs/README.md`, `docs/phoenix/skill.md`, `AGENTS.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`packages/phoenix-otel/docs/README.md`, `docs/phoenix/skill.md`, `AGENTS.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Project Overview**：importance `high`\n - source_paths: README.md, pyproject.toml, js/pnpm-workspace.yaml\n- **System Architecture**：importance `high`\n - source_paths: app/schema.graphql, src/phoenix/server/__init__.py, schemas/openapi.json\n- **Tracing System**：importance `high`\n - source_paths: src/phoenix/server/api/dataloaders/trace_retention_policy_id_by_project_id.py, src/phoenix/db/insertion/span.py, src/phoenix/db/insertion/trace_annotation.py, src/phoenix/db/insertion/span_annotation.py, src/phoenix/db/insertion/session_annotation.py\n- **OpenTelemetry Integration**：importance `high`\n - source_paths: packages/phoenix-otel/src/phoenix/otel/otel.py, packages/phoenix-otel/src/phoenix/otel/settings.py, js/packages/phoenix-otel/src/index.ts, js/packages/phoenix-otel/src/register.ts\n- **Evaluation System (Phoenix Evals)**：importance `high`\n - source_paths: packages/phoenix-evals/pyproject.toml, prompts/classification_evaluator_configs, js/packages/phoenix-evals/src/llm/createCorrectnessEvaluator.ts, js/packages/phoenix-evals/src/llm/createFaithfulnessEvaluator.ts, src/phoenix/server/api/helpers/evaluators.py\n- **Datasets and Experiments**：importance `high`\n - source_paths: src/phoenix/db/insertion/dataset.py, src/phoenix/server/api/input_types/CreateDatasetInput.py, src/phoenix/server/api/input_types/AddExamplesToDatasetInput.py, src/phoenix/db/insertion/document_annotation.py\n- **Database Models and Migrations**：importance `medium`\n - source_paths: src/phoenix/db/models.py, src/phoenix/db/migrations/versions/cf03bd6bae1d_init.py, src/phoenix/db/engines.py, src/phoenix/db/bulk_inserter.py\n- **Frontend Application**：importance `medium`\n - source_paths: app/src/App.tsx, app/src/Routes.tsx, app/src/pages/trace/TraceTree.tsx, app/src/pages/playground/Playground.tsx, app/src/components\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `a3299461accfcdf66bf983d95bc2cf0bd3229170`\n- inspected_files: `pyproject.toml`, `Dockerfile`, `README.md`, `docker-compose.yml`, `uv.lock`, `docs/PROMPT.md`, `docs/openapi.json`, `docs/phoenix.mdx`, `docs/analytics.js`, `docs/phoenix/phoenix-cloud.mdx`, `docs/phoenix/sdk-api-reference.mdx`, `docs/phoenix/self-hosting.mdx`, `docs/phoenix/get-started.mdx`, `docs/phoenix/integrations.mdx`, `docs/phoenix/agent-assisted-setup.mdx`, `docs/phoenix/user-guide.mdx`, `docs/phoenix/release-notes.mdx`, `docs/phoenix/end-to-end-features-notebook.mdx`, `docs/phoenix/cookbook.mdx`, `docs/phoenix/skill.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：Docs proposal: RAG failure mode checklist for observability and eval workflows\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docs proposal: RAG failure mode checklist for observability and eval workflows\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_43a673bd0a9947d3a8758a608e7a5a15 | https://github.com/Arize-ai/phoenix/issues/11472 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：[BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47.0.0 incompatible with App…\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47.0.0 incompatible with Apple Hypervisor VM\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_beadd6130d804f29b2f261a0194d2262 | https://github.com/Arize-ai/phoenix/issues/12941 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：[agents] investigate clientside tracing for external tools\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[agents] investigate clientside tracing for external tools\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2e2fc634da044ed9a177a6dd85a78b23 | https://github.com/Arize-ai/phoenix/issues/13173 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 失败模式：installation: [BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47...\n\n- Trigger: Developers should check this installation risk before relying on the project: [BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47.0.0 incompatible with Apple Hypervisor VM\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: [BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47.0.0 incompatible with Apple Hypervisor VM. Context: Observed when using python, docker, linux\n- Why it matters: Developers may fail before the first successful local run: [BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47.0.0 incompatible with Apple Hypervisor VM\n- Evidence: failure_mode_cluster:github_issue | fmev_b3db5f930ac5e7b7f85e47ff9693c190 | https://github.com/Arize-ai/phoenix/issues/12941 | [BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47.0.0 incompatible with Apple Hypervisor VM\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 失败模式：configuration: [sandboxes] per-execute timeout enforcement is incomplete across backends\n\n- Trigger: Developers should check this configuration risk before relying on the project: [sandboxes] per-execute timeout enforcement is incomplete across backends\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: [sandboxes] per-execute timeout enforcement is incomplete across backends. Context: Observed when using python\n- Why it matters: Developers may misconfigure credentials, environment, or host setup: [sandboxes] per-execute timeout enforcement is incomplete across backends\n- Evidence: failure_mode_cluster:github_issue | fmev_5978fbc9db2aea6762b2ab2f9e8d0205 | https://github.com/Arize-ai/phoenix/issues/13313 | [sandboxes] per-execute timeout enforcement is incomplete across backends\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：[sandboxes] per-execute timeout enforcement is incomplete across backends\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[sandboxes] per-execute timeout enforcement is incomplete across backends\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_7e0ad954523449959675c0433a0ff80b | https://github.com/Arize-ai/phoenix/issues/13313 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:564072810 | https://github.com/Arize-ai/phoenix | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 失败模式：runtime: arize-phoenix: v15.5.0\n\n- Trigger: Developers should check this runtime risk before relying on the project: arize-phoenix: v15.5.0\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: arize-phoenix: v15.5.0. Context: Observed when using docker\n- Why it matters: Upgrade or migration may change expected behavior: arize-phoenix: v15.5.0\n- Evidence: failure_mode_cluster:github_release | fmev_77bc9f7097156e71a699d05abced2916 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.0 | arize-phoenix: v15.5.0\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：arize-phoenix: v15.3.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.3.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_d364a0a28a14428baff5ca692cb00578 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.3.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：arize-phoenix: v15.5.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.5.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ad2696a72e314b52b79d157bf261f7bd | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：Arize-ai/phoenix\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Docs proposal: RAG failure mode checklist for observability and eval workflows（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47.0.0 incompatible with App…（high）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[agents] investigate clientside tracing for external tools（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 失败模式：installation: [BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47...（medium）：Developers may fail before the first successful local run: [BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47.0.0 incompatible with Apple Hypervisor VM 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG]: Docker image exits immediately (SIGILL) on Apple Silicon with podman — cryptography 47.0.0 incompatible with Apple Hypervisor VM. Context: Observed when using python, docker, linux\n- 失败模式：configuration: [sandboxes] per-execute timeout enforcement is incomplete across backends（medium）：Developers may misconfigure credentials, environment, or host setup: [sandboxes] per-execute timeout enforcement is incomplete across backends 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [sandboxes] per-execute timeout enforcement is incomplete across backends. Context: Observed when using python\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/Arize-ai/phoenix 项目说明书\n\n生成时间：2026-05-16 08:30:37 UTC\n\n## 目录\n\n- [Project Overview](#page-project-overview)\n- [System Architecture](#page-system-architecture)\n- [Tracing System](#page-tracing-system)\n- [OpenTelemetry Integration](#page-otel-integration)\n- [Evaluation System (Phoenix Evals)](#page-evals-system)\n- [Datasets and Experiments](#page-datasets-experiments)\n- [Database Models and Migrations](#page-database-models)\n- [Frontend Application](#page-frontend-components)\n- [Server API and GraphQL](#page-server-api)\n- [Python SDK (arize-phoenix-client)](#page-python-sdk)\n\n\n\n## Project Overview\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Arize-ai/phoenix/blob/main/README.md)\n- [js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n- [app/src/components/project/PythonProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/PythonProjectGuide.tsx)\n- [app/src/components/project/TypeScriptProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/TypeScriptProjectGuide.tsx)\n- [app/src/pages/project/OnboardingSteps.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/OnboardingSteps.tsx)\n- [js/packages/phoenix-mcp/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-mcp/README.md)\n- [js/packages/phoenix-evals/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/README.md)\n- [js/examples/apps/cli-agent-starter-kit/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/examples/apps/cli-agent-starter-kit/README.md)\n\n\n# Project Overview\n\nPhoenix is an open-source observability platform for AI applications developed by Arize AI. It provides comprehensive tracing, evaluation, and debugging capabilities for LLM-powered applications, agents, and vector retrieval systems.\n\n## What is Phoenix?\n\nPhoenix is a self-hostable observability platform designed to help developers:\n\n- **Trace LLM applications**: Capture and analyze spans, prompts, completions, and tool executions\n- **Evaluate AI outputs**: Run automated evaluations for hallucinations, relevance, toxicity, and custom metrics\n- **Debug retrievals**: Inspect vector search operations and document retrieval pipelines\n- **Monitor performance**: Track latency, token usage, and cost metrics across AI workflows\n\n资料来源：[js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n\n## Architecture Overview\n\nPhoenix follows a multi-layer architecture with Python backend services and TypeScript/JavaScript client libraries.\n\n```mermaid\ngraph TD\n A[AI Application] -->|OTel Traces| B[Phoenix OTEL]\n A -->|Direct API| C[Phoenix Client SDK]\n B -->|Traces| D[Phoenix Server]\n C -->|Data| D\n D -->|UI| E[Phoenix Web UI]\n F[Phoenix MCP Server] -->|Tools| A\n G[Phoenix Evals] -->|Evaluations| D\n```\n\n### Core Components\n\n| Component | Technology | Purpose |\n|-----------|------------|---------|\n| Phoenix Server | Python | Backend API and data storage |\n| Phoenix OTEL | Python | OpenTelemetry instrumentation |\n| Phoenix Client | TypeScript | Type-safe API access |\n| Phoenix Config | TypeScript | Environment variable parsing |\n| Phoenix MCP | TypeScript | Model Context Protocol server |\n| Phoenix Evals | TypeScript | LLM-based evaluation library |\n\n资料来源：[js/pnpm-workspace.yaml](https://github.com/Arize-ai/phoenix/blob/main/js/pnpm-workspace.yaml)\n\n## JavaScript/TypeScript Packages\n\nPhoenix provides a comprehensive TypeScript ecosystem organized as a pnpm workspace.\n\n资料来源：[js/pnpm-workspace.yaml](https://github.com/Arize-ai/phoenix/blob/main/js/pnpm-workspace.yaml)\n\n### Package Structure\n\n```\njs/\n├── packages/\n│ ├── phoenix-client/ # Core API client\n│ ├── phoenix-config/ # Environment variable utilities\n│ ├── phoenix-evals/ # Evaluation library\n│ └── phoenix-mcp/ # Model Context Protocol server\n└── examples/\n └── apps/\n └── cli-agent-starter-kit/ # Example CLI agent\n```\n\n### phoenix-config\n\nShared configuration parsing utilities used across other Phoenix packages. Provides typed helpers for reading Phoenix environment variables.\n\n资料来源：[js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n\n### phoenix-evals\n\nA vendor-agnostic TypeScript evaluation library for assessing AI output quality. Supports custom classifiers for hallucination detection, relevance scoring, and binary/multi-class classification tasks.\n\n```typescript\nimport { createClassifier } from \"@arizeai/phoenix-evals/llm\";\nimport { openai } from \"@ai-sdk/openai\";\n\nconst model = openai(\"gpt-4o-mini\");\nconst classifier = createClassifier({ model, promptTemplate });\n```\n\n资料来源：[js/packages/phoenix-evals/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/README.md)\n\n### phoenix-mcp\n\nA Model Context Protocol server that exposes Phoenix tools for AI agents. Enables agentic workflows to interact with Phoenix data.\n\n**Supported Tools:**\n- **Prompts**: list-prompts, get-prompt, get-latest-prompt, upsert-prompt\n- **Projects**: Project management operations\n- **Traces**: Query and analyze traces\n\n资料来源：[js/packages/phoenix-mcp/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-mcp/README.md)\n\n## Python SDK\n\nPhoenix provides Python instrumentation through the `arize-phoenix-otel` package.\n\n资料来源：[app/src/components/project/PythonProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/PythonProjectGuide.tsx)\n\n### Installation\n\n```bash\npip install arize-phoenix-otel\n```\n\n### Quick Start\n\n```python\nfrom phoenix.otel import register\n\n# Configure Phoenix tracing\ntracer_provider = register(project_name=\"my-app\")\n```\n\nThe `arize-phoenix-otel` package automatically picks up configuration from environment variables, simplifying the setup process for developers.\n\n资料来源：[app/src/components/project/PythonProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/PythonProjectGuide.tsx)\n\n## Environment Variables\n\nPhoenix uses standardized environment variables for configuration across all SDKs.\n\n资料来源：[js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n\n| Variable | Constant | Description |\n|----------|----------|-------------|\n| `PHOENIX_HOST` | `ENV_PHOENIX_HOST` | Phoenix server URL (e.g., `http://localhost:6006`) |\n| `PHOENIX_API_KEY` | `ENV_PHOENIX_API_KEY` | API key for authentication |\n| `PHOENIX_CLIENT_HEADERS` | `ENV_PHOENIX_CLIENT_HEADERS` | JSON-encoded custom headers |\n| `PHOENIX_COLLECTOR_ENDPOINT` | `ENV_PHOENIX_COLLECTOR_ENDPOINT` | OTel collector endpoint |\n| `PHOENIX_PORT` | `ENV_PHOENIX_PORT` | HTTP port (integer) |\n| `PHOENIX_GRPC_PORT` | `ENV_PHOENIX_GRPC_PORT` | gRPC port for OpenTelemetry |\n| `PHOENIX_PROJECT` | `ENV_PHOENIX_PROJECT` | Default project name |\n\n## Project Onboarding Flow\n\nPhoenix provides an interactive onboarding system that guides users through setup.\n\n资料来源：[app/src/pages/project/OnboardingSteps.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/OnboardingSteps.tsx)\n\n### Onboarding Steps Component\n\nThe `OnboardingSteps` component accepts the following parameters:\n\n```typescript\ninterface OnboardingStepsProps {\n language: ProgrammingLanguage;\n packages: readonly string[];\n implementationCode: string;\n docsHref?: string;\n githubHref?: string;\n generatedApiKey: string | null;\n onApiKeyGenerated: (key: string) => void;\n extraEnvVars?: readonly EnvVar[];\n}\n```\n\n### Workflow\n\n```mermaid\ngraph LR\n A[Select Language] --> B[Install Packages]\n B --> C[Configure Environment]\n C --> D{Auth Enabled?}\n D -->|Yes| E[Generate API Key]\n D -->|No| F[Add Environment Variables]\n E --> G[Copy Setup Code]\n F --> G\n G --> H[Run Application]\n H --> I[View Traces in Phoenix]\n```\n\nThe onboarding system automatically detects authentication requirements and adjusts the setup flow accordingly. Users can generate API keys directly from the UI when authentication is enabled.\n\n资料来源：[app/src/components/project/PythonProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/PythonProjectGuide.tsx)\n\n## CLI Agent Starter Kit\n\nPhoenix includes a complete CLI agent example demonstrating production-ready patterns.\n\n资料来源：[js/examples/apps/cli-agent-starter-kit/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/examples/apps/cli-agent-starter-kit/README.md)\n\n### Project Structure\n\n```\nsrc/\n├── cli.ts # Entry point\n├── agent/ # Agent factory\n├── tools/ # Tool definitions\n│ ├── index.ts # Tool exports\n│ ├── datetime.ts # Utility tool\n│ └── mcp.ts # Phoenix docs MCP\n├── prompts/ # System instructions\n└── ui/ # CLI interface\n```\n\n### Requirements\n\n- Node.js 22+\n- pnpm\n- Docker Desktop\n- Anthropic API key\n\n### Quick Start\n\n```bash\npnpm install\ncp .env.example .env\n# Add ANTHROPIC_API_KEY to .env\npnpm dev\n```\n\nPhoenix UI will be available at http://localhost:6006.\n\n资料来源：[js/examples/apps/cli-agent-starter-kit/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/examples/apps/cli-agent-starter-kit/README.md)\n\n## Integration Ecosystem\n\nPhoenix supports a wide range of LLM providers and frameworks through its integration ecosystem.\n\n### Supported Providers\n\n| Provider | Icon | Category |\n|----------|------|----------|\n| OpenAI | SVG | LLM |\n| Anthropic | SVG | LLM |\n| LiteLLM | SVG | Proxy |\n| OpenRouter | SVG | Proxy |\n| LangGraph | SVG | Framework |\n| Moonshot | SVG | LLM |\n| xAI | SVG | LLM |\n| Ollama | SVG | Local |\n\n资料来源：[app/src/components/project/IntegrationIcons.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/IntegrationIcons.tsx)\n\n## Development Workflow\n\n### Setting Up the JavaScript Workspace\n\n```bash\n# From the /js/ directory\npnpm install\npnpm build\n```\n\n### Development Mode\n\n```bash\npnpm dev\n```\n\n### Building\n\n```bash\npnpm build\n```\n\n### Debugging MCP Server\n\n```bash\npnpm inspect\n```\n\n资料来源：[js/packages/phoenix-mcp/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-mcp/README.md)\n\n## Summary\n\nPhoenix is a comprehensive observability platform that bridges the gap between development and production monitoring for AI applications. Its multi-language support (Python and TypeScript), OpenTelemetry-native architecture, and extensible evaluation framework make it suitable for teams of all sizes building LLM-powered products.\n\nThe platform's modular design allows developers to adopt only the components they need—whether that's basic tracing through OTEL, custom evaluations with the evals library, or full agentic observability through the MCP server.\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Project Overview](#page-project-overview), [Server API and GraphQL](#page-server-api), [Frontend Application](#page-frontend-components)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n- [app/src/components/project/PythonProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/PythonProjectGuide.tsx)\n- [app/src/components/project/TypeScriptProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/TypeScriptProjectGuide.tsx)\n- [app/src/components/experiment/RunExperimentCodeDialog.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/experiment/RunExperimentCodeDialog.tsx)\n- [app/src/components/project/OnboardingSteps.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/OnboardingSteps.tsx)\n- [app/src/components/markdown/streamdownComponents.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/markdown/streamdownComponents.tsx)\n- [app/src/components/generative/GenerativeProviderIcon.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/generative/GenerativeProviderIcon.tsx)\n- [app/src/components/core/icon/Icons.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/core/icon/Icons.tsx)\n- [api_reference/README.md](https://github.com/Arize-ai/phoenix/blob/main/api_reference/README.md)\n\n\n# System Architecture\n\n## Overview\n\nPhoenix is an LLM observability platform designed to help developers trace, evaluate, and debug AI applications. The system architecture follows a client-server model with support for multiple programming languages and observability standards.\n\n## Core Components\n\nThe Phoenix platform consists of three primary layers:\n\n| Component Layer | Description | Key Technologies |\n|-----------------|-------------|------------------|\n| **Frontend Application** | React-based web UI for visualization and interaction | React, TypeScript, @arizeai/ui |\n| **Configuration Library** | Shared utilities for environment parsing | TypeScript, npm package (@arizeai/phoenix-config) |\n| **Backend Server** | Phoenix server for data ingestion and serving | Python, FastAPI, OpenTelemetry |\n\n## Configuration System\n\nPhoenix uses environment variables for configuration across all client SDKs and the server itself.\n\n### Environment Variables Table\n\n| Variable | Constant | Type | Purpose |\n|----------|----------|------|---------|\n| `PHOENIX_HOST` | `ENV_PHOENIX_HOST` | string | Phoenix server host URL (e.g., `http://localhost:6006`) |\n| `PHOENIX_API_KEY` | `ENV_PHOENIX_API_KEY` | string | API key for authentication |\n| `PHOENIX_CLIENT_HEADERS` | `ENV_PHOENIX_CLIENT_HEADERS` | JSON | Custom headers for client requests |\n| `PHOENIX_COLLECTOR_ENDPOINT` | `ENV_PHOENIX_COLLECTOR_ENDPOINT` | string | OpenTelemetry collector endpoint URL |\n| `PHOENIX_PORT` | `ENV_PHOENIX_PORT` | integer | Phoenix HTTP port |\n| `PHOENIX_GRPC_PORT` | `ENV_PHOENIX_GRPC_PORT` | integer | Phoenix gRPC port for OpenTelemetry |\n| `PHOENIX_PROJECT` | `ENV_PHOENIX_PROJECT` | string | Default project name for project-scoped operations |\n\n资料来源：[js/packages/phoenix-config/README.md:1-25](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n\n## Client Architecture\n\n### Multi-Language SDK Support\n\nPhoenix provides language-specific client libraries that interface with the Phoenix server.\n\n```mermaid\ngraph TD\n A[Application Code] --> B[Phoenix OTEL / SDK]\n B --> C[Phoenix Server]\n C --> D[(Data Storage)]\n \n subgraph Python Ecosystem\n B1[arize-phoenix-otel]\n B1 --> B\n end\n \n subgraph TypeScript Ecosystem\n B2[phoenix-otel]\n B3[phoenix-client]\n B2 --> B\n B3 --> B\n end\n```\n\n### Python Client\n\nThe Python integration uses OpenTelemetry for automatic instrumentation.\n\n**Installation:**\n```bash\npip install arize-phoenix-otel\n```\n\nThe `arize-phoenix-otel` package automatically picks up configuration from environment variables, enabling seamless integration without explicit setup code in most cases.\n\n资料来源：[app/src/components/project/PythonProjectGuide.tsx:1-35](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/PythonProjectGuide.tsx)\n\n### TypeScript/Node.js Client\n\nThe TypeScript ecosystem provides two main packages:\n\n| Package | Purpose |\n|---------|---------|\n| `@arizeai/phoenix-otel` | OpenTelemetry instrumentation for tracing |\n| `@arizeai/phoenix-client` | Client library for API interactions |\n\n**Quick Start Pattern:**\n```typescript\nimport { register } from '@arizeai/phoenix-otel';\n\n// Project setup with automatic OTEL initialization\nregister({ projectName: 'my-project' });\n```\n\n资料来源：[app/src/components/project/TypeScriptProjectGuide.tsx:1-25](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/TypeScriptProjectGuide.tsx)\n\n## Authentication Architecture\n\nPhoenix implements API key-based authentication with role-based access control.\n\n### Authentication Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant PhoenixServer\n participant Config\n \n Client->>PhoenixServer: Request with API Key\n PhoenixServer->>Config: Check authentication settings\n Config-->>PhoenixServer: authenticationEnabled: boolean\n alt Authentication Enabled\n PhoenixServer->>PhoenixServer: Validate API Key\n alt Valid Key\n PhoenixServer-->>Client: 200 OK + Data\n else Invalid Key\n PhoenixServer-->>Client: 401 Unauthorized\n end\n else Authentication Disabled\n PhoenixServer-->>Client: 200 OK + Data\n end\n```\n\n### API Key Management\n\nThe UI provides different API key management interfaces based on user roles:\n\n| Role | API Key Management Location |\n|------|---------------------------|\n| Admin | Settings → General |\n| Regular User | Profile Page |\n\n资料来源：[app/src/components/project/OnboardingSteps.tsx:30-55](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/OnboardingSteps.tsx)\n\n## Dataset Management\n\nPhoenix clients can interact with datasets through the Python and TypeScript client libraries.\n\n### Dataset Operations\n\n| Operation | Description |\n|-----------|-------------|\n| Create | Initialize a new dataset in the project |\n| Get | Retrieve dataset by name or version |\n| Update | Modify existing dataset metadata |\n| List | Enumerate all available datasets |\n\n**Python Client Pattern:**\n```python\nclient = Client()\ndataset = client.datasets.get_dataset(\n dataset=\"my-dataset\",\n version_id=\"optional-version-id\"\n)\n```\n\n资料来源：[app/src/components/experiment/RunExperimentCodeDialog.tsx:1-45](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/experiment/RunExperimentCodeDialog.tsx)\n\n## Generative AI Provider Integration\n\nPhoenix integrates with multiple generative AI providers for observability and tracing.\n\n### Supported Providers\n\n| Provider | SVG Icon | Integration Type |\n|----------|----------|------------------|\n| OpenAI | ✓ | API Key + OTEL |\n| Moonshot | ✓ | API Key |\n| LiteLLM | ✓ | Unified API |\n| Agno | ✓ | Agent Framework |\n| OpenRouter | ✓ | Gateway |\n| Anthropic | ✓ | Direct |\n\nThe `GenerativeProviderIcon.tsx` component renders provider-specific SVG icons throughout the UI, while the `IntegrationIcons.tsx` file contains SVG definitions for all supported integrations.\n\n资料来源：[app/src/components/generative/GenerativeProviderIcon.tsx:1-60](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/generative/GenerativeProviderIcon.tsx)\n\n## UI Component Architecture\n\n### Component Hierarchy\n\n```mermaid\ngraph TD\n subgraph Project Guides\n PG1[PythonProjectGuide]\n PG2[TypeScriptProjectGuide]\n end\n \n subgraph Core Components\n OC[OnboardingSteps]\n MD[Markdown Components]\n IC[Icons]\n end\n \n subgraph Experiment Features\n RX[RunExperimentCodeDialog]\n end\n \n OC --> PG1\n OC --> PG2\n IC --> PG1\n IC --> PG2\n MD --> RX\n```\n\n### Markdown Rendering\n\nThe `streamdownComponents.tsx` module provides custom React components for rendering markdown content:\n\n| Component | Purpose |\n|-----------|---------|\n| `li` | Task list items with checkbox support |\n| `blockquote` | Styled quote blocks |\n| `inlineCode` | Inline code styling |\n| `table`, `thead`, `tbody`, `tr`, `th`, `td` | Table elements |\n| `img` | Styled images |\n| `hr` | Horizontal rules |\n\n资料来源：[app/src/components/markdown/streamdownComponents.tsx:1-55](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/markdown/streamdownComponents.tsx)\n\n## Icon System\n\nPhoenix uses a centralized icon system defined in `Icons.tsx`. Icons follow a consistent design pattern:\n\n```typescript\nexport const IconName = () => (\n \n {/* SVG path definitions */}\n \n);\n```\n\nKey icon categories include:\n- **Navigation**: ArrowCompareOutline, MoonOutline\n- **Actions**: TemplateOutline\n- **Status**: FireOutline\n\n资料来源：[app/src/components/core/icon/Icons.tsx:1-120](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/core/icon/Icons.tsx)\n\n## Documentation Architecture\n\nPhoenix uses Sphinx for API documentation generation with autodoc support.\n\n### Documentation Build Process\n\n```mermaid\ngraph LR\n A[Source Modules] -->|sphinx-apidoc| B[RST Files]\n B -->|autodoc| C[Docstrings]\n C --> D[HTML/Markdown Output]\n \n subgraph Build Tools\n B1[Sphinx]\n B2[ReadTheDocs]\n end\n```\n\n### Sphinx-Apidoc Command\n\n```bash\nsphinx-apidoc -o ./source/output ../path/to/module --separate -M\n```\n\nKey options:\n- `--separate`: Creates separate .rst files per module\n- `-M`: Use module names instead of file names for titles\n\n资料来源：[api_reference/README.md:1-80](https://github.com/Arize-ai/phoenix/blob/main/api_reference/README.md)\n\n## OpenTelemetry Integration\n\nPhoenix leverages OpenTelemetry as the standard observability framework:\n\n### Collector Endpoint Configuration\n\n```mermaid\ngraph LR\n A[Application] -->|OTLP| B[Phoenix Collector]\n B --> C[Phoenix Server]\n \n subgraph Transport Protocols\n G[gRPC]\n H[HTTP/protobuf]\n end\n \n B --- G\n B --- H\n```\n\n| Port Type | Purpose |\n|-----------|---------|\n| HTTP (configurable) | OTLP HTTP receiver |\n| gRPC (configurable) | OTLP gRPC receiver |\n\n资料来源：[js/packages/phoenix-config/README.md:15-16](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n\n## Security Considerations\n\n### Environment Variable Security\n\n| Variable | Sensitivity | Recommendation |\n|----------|-------------|----------------|\n| `PHOENIX_API_KEY` | High | Store in secure secret manager |\n| `PHOENIX_CLIENT_HEADERS` | Medium | Validate JSON structure |\n| `PHOENIX_HOST` | Low | Ensure HTTPS for production |\n\n### API Key Scopes\n\n- **Personal API Keys**: Created per-user, managed on Profile page\n- **System API Keys**: Admin-managed, configured in Settings\n\n## Summary\n\nThe Phoenix system architecture provides a robust, multi-language observability platform with:\n\n1. **Flexible Configuration**: Environment-based configuration works across all SDKs\n2. **Multi-language Support**: Native Python and TypeScript clients\n3. **Standard Observability**: OpenTelemetry integration for vendor-neutral tracing\n4. **Role-based Access**: Enterprise-ready authentication and authorization\n5. **Extensible Providers**: Support for multiple LLM providers through standardized interfaces\n\n---\n\n\n\n## Tracing System\n\n### 相关页面\n\n相关主题：[OpenTelemetry Integration](#page-otel-integration), [Database Models and Migrations](#page-database-models)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/phoenix/server/api/dataloaders/trace_retention_policy_id_by_project_id.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/dataloaders/trace_retention_policy_id_by_project_id.py)\n- [src/phoenix/db/insertion/span.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/insertion/span.py)\n- [src/phoenix/db/insertion/trace_annotation.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/insertion/trace_annotation.py)\n- [src/phoenix/db/insertion/span_annotation.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/insertion/span_annotation.py)\n- [src/phoenix/db/insertion/session_annotation.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/insertion/session_annotation.py)\n- [js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n- [js/packages/phoenix-otel/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-otel/README.md)\n- [js/examples/apps/langchain-quickstart/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/examples/apps/langchain-quickstart/README.md)\n\n\n# Tracing System\n\nPhoenix's Tracing System provides comprehensive observability for LLM applications by capturing, storing, and analyzing execution traces. It leverages OpenTelemetry standards to instrument applications and provides both Python and TypeScript clients for interacting with trace data.\n\n## Overview\n\nThe tracing system enables developers to:\n\n- Capture detailed execution traces from LLM applications\n- Store and query traces with filtering by time, session, and project\n- Add annotations for evaluation and human feedback\n- Analyze spans within traces for debugging and performance optimization\n\n资料来源：[js/packages/phoenix-client/README.md:1-30]()\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Application Code] --> B[Phoenix OTEL]\n B --> C[Span Exporter]\n C --> D[Phoenix Server]\n D --> E[(SQLite/PostgreSQL)]\n \n F[Python Client] --> D\n G[TypeScript Client] --> D\n \n H[Spans] --> E\n I[Trace Annotations] --> E\n J[Span Annotations] --> E\n K[Session Annotations] --> E\n```\n\nThe system consists of three main layers:\n\n1. **Instrumentation Layer**: OpenTelemetry-based tracing via `arize-phoenix-otel`\n2. **Storage Layer**: Database insertion handlers for traces, spans, and annotations\n3. **API Layer**: REST endpoints for querying and managing trace data\n\n资料来源：[js/packages/phoenix-otel/README.md:1-50]()\n\n## Core Components\n\n### Spans\n\nSpans represent individual units of work within a trace. Each span captures:\n\n- **Timing information**: start time, end time, duration\n- **Input/output data**: prompts, responses, tool parameters\n- **Attributes**: metadata like model name, token counts, latency\n\n资料来源：[src/phoenix/db/insertion/span.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/insertion/span.py)\n\n### Trace Annotations\n\nAnnotations attached at the trace level for evaluation purposes. Used to store:\n\n- Correctness scores\n- Custom evaluation results\n- Human feedback\n\n资料来源：[src/phoenix/db/insertion/trace_annotation.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/insertion/trace_annotation.py)\n\n### Span Annotations\n\nAnnotations attached to individual spans for fine-grained evaluation:\n\n```python\nfrom phoenix.client import Client\n\nclient = Client()\n\n# Add annotation to a span\nclient.spans.add_span_annotation(\n span_id=\"span-123\",\n project_identifier=\"my-llm-app\",\n name=\"correctness\",\n value=0.95,\n annotator_kind=\"LLM\"\n)\n```\n\n资料来源：[src/phoenix/db/insertion/span_annotation.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/insertion/span_annotation.py)\n\n### Session Annotations\n\nAnnotations at the session level for grouping related spans:\n\n资料来源：[src/phoenix/db/insertion/session_annotation.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/insertion/session_annotation.py)\n\n### Trace Retention Policy\n\nData loaders manage trace retention policies per project:\n\n资料来源：[src/phoenix/server/api/dataloaders/trace_retention_policy_id_by_project_id.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/dataloaders/trace_retention_policy_id_by_project_id.py)\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Constant | Description | Example |\n|----------|----------|-------------|---------|\n| `PHOENIX_HOST` | `ENV_PHOENIX_HOST` | Phoenix server host URL | `http://localhost:6006` |\n| `PHOENIX_API_KEY` | `ENV_PHOENIX_API_KEY` | API key for authentication | `your-api-key` |\n| `PHOENIX_CLIENT_HEADERS` | `ENV_PHOENIX_CLIENT_HEADERS` | JSON-encoded custom headers | `{\"X-Custom\":\"value\"}` |\n| `PHOENIX_COLLECTOR_ENDPOINT` | `ENV_PHOENIX_COLLECTOR_ENDPOINT` | OTel collector endpoint URL | `https://app.phoenix.arize.com/s/space` |\n| `PHOENIX_PROJECT_NAME` | `ENV_PHOENIX_PROJECT` | Default project name | `my-llm-app` |\n| `PHOENIX_PORT` | `ENV_PHOENIX_PORT` | HTTP port (integer) | `6006` |\n| `PHOENIX_GRPC_PORT` | `ENV_PHOENIX_GRPC_PORT` | gRPC port for OTEL | `4317` |\n\n资料来源：[js/packages/phoenix-config/README.md:1-50]()\n\n### Python Client Configuration\n\n```python\nfrom phoenix.client import Client\n\n# Environment-based configuration\nclient = Client()\n\n# Explicit configuration\nclient = Client(\n host=\"http://localhost:6006\",\n api_key=\"your-api-key\"\n)\n```\n\n资料来源：[js/packages/phoenix-client/README.md:50-100]()\n\n### OTEL Registration Options\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `projectName` | `string` | `\"default\"` | Project name for organizing traces |\n| `url` | `string` | `\"http://localhost:6006\"` | Phoenix instance URL |\n| `apiKey` | `string` | `undefined` | API key for authentication |\n| `headers` | `Record` | `{}` | Custom headers for OTLP requests |\n| `batch` | `boolean` | `true` | Use batch span processing |\n| `instrumentations` | `Instrumentation[]` | `undefined` | OpenTelemetry instrumentations |\n\n资料来源：[js/packages/phoenix-otel/README.md:80-120]()\n\n## Querying Traces\n\n### Python Client API\n\n```python\nfrom phoenix.client import Client\nfrom datetime import datetime, timedelta\n\nclient = Client()\n\n# Get latest traces\ntraces = client.traces.get_traces(\n project_identifier=\"my-llm-app\",\n limit=10\n)\n\n# Filter by time range with span details\ntraces = client.traces.get_traces(\n project_identifier=\"my-llm-app\",\n start_time=datetime.now() - timedelta(hours=24),\n end_time=datetime.now(),\n include_spans=True,\n sort=\"latency_ms\",\n order=\"desc\"\n)\n\n# Filter by session\ntraces = client.traces.get_traces(\n project_identifier=\"my-llm-app\",\n session_id=\"my-session-id\"\n)\n```\n\n资料来源：[js/packages/phoenix-client/README.md:100-150]()\n\n### TypeScript Client API\n\n```typescript\nimport { getTraces } from \"@arizeai/phoenix-client/traces\";\n\nconst result = await getTraces({\n project: { projectName: \"my-project\" },\n limit: 10,\n});\n\nconst detailed = await getTraces({\n project: { projectName: \"my-project\" },\n startTime: \"2026-03-01T00:00:00Z\",\n endTime: new Date(),\n includeSpans: true,\n sort: \"latency_ms\",\n order: \"desc\"\n});\n```\n\n### Query Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `project_identifier` | `string` | — | Project name or ID (required) |\n| `start_time` | `datetime \\| None` | `None` | Inclusive lower bound on trace start time |\n| `end_time` | `datetime \\| None` | `None` | Exclusive upper bound on trace start time |\n| `sort` | `\"start_time\" \\| \"latency_ms\" \\| None` | `None` | Sort field |\n| `order` | `\"asc\" \\| \"desc\" \\| None` | `None` | Sort direction |\n| `include_spans` | `bool` | `False` | Include full span details |\n| `session_id` | `str \\| Sequence[str] \\| None` | `None` | Filter by session ID(s) |\n| `limit` | `int` | `100` | Maximum traces to return |\n| `timeout` | `int \\| None` | `60` | Request timeout in seconds |\n\n> **Note:** Requires Phoenix server >= 13.15.0.\n\n资料来源：[js/packages/phoenix-client/README.md:150-200]()\n\n## Instrumentation\n\n### Basic Setup (Python)\n\n```python\nfrom phoenix.otel import register\n\ntracer_provider = register(\n project_name=\"my-llm-app\",\n auto_instrument=True, # Auto-trace AI/ML libraries\n batch=True, # Background batching\n api_key=\"your-api-key\", # Authentication\n endpoint=\"https://app.phoenix.arize.com/s/your-space\"\n)\n```\n\n### Using Decorators\n\n```python\nfrom phoenix.otel import register\n\ntracer_provider = register()\n\n# Get a tracer for manual instrumentation\ntracer = tracer_provider.get_tracer(__name__)\n\n@tracer.chain\ndef process_data(data):\n return data + \" processed\"\n\n@tracer.tool\ndef weather(location):\n return \"sunny\"\n```\n\n资料来源：[js/packages/phoenix-otel/README.md:50-80]()\n\n### LangChain Integration\n\n```typescript\nimport { register, traceChain } from \"@arizeai/phoenix-otel\";\n\nconst provider = register({\n projectName: \"my-app\",\n});\n\nconst answerQuestion = traceChain(\n async (question: string) => `Handled: ${question}`,\n { name: \"answer-question\" }\n);\n\nawait answerQuestion(\"What is Phoenix?\");\nawait provider.shutdown();\n```\n\n资料来源：[js/examples/apps/langchain-quickstart/README.md:50-80]()\n\n## Data Flow\n\n```mermaid\ngraph LR\n A[Application] -->|OpenTelemetry| B[Phoenix OTEL]\n B --> C[Span Processor]\n C --> D[Batch Span Processor]\n D --> E[HTTPSpanExporter]\n E --> F[Phoenix Server API]\n F --> G[DB Insertion Handlers]\n G --> H[(Database)]\n \n I[Query Client] --> F\n J[Annotations] --> G\n```\n\n## Trace Visualization\n\nWhen viewing traces in Phoenix UI, each trace displays:\n\n- **LangGraph (agent) span** with input messages and final output\n- **Tool calls** with their parameters and results\n- **Token usage** and latency metrics\n- **Prompts and responses** for each span\n\nAfter running evaluations, span annotations appear on the relevant spans (e.g., `correctness` / `custom_correctness`).\n\n资料来源：[js/examples/apps/langchain-quickstart/README.md:20-45]()\n\n## Integration with Phoenix Client\n\n### Dataset Operations with Traces\n\n```python\nfrom phoenix.client import Client\n\nclient = Client()\n\n# Get dataset for evaluation\ndataset = client.datasets.get_dataset(\n dataset=\"my-dataset\",\n version_id=\"v1\"\n)\n\n# Run experiment with traces\nexperiment = client.experiments.run(\n dataset_id=dataset.id,\n task=my_task,\n evaluators=[correctness_evaluator],\n)\n```\n\n> **Hint:** Tasks and evaluators are instrumented using OpenTelemetry. You can view detailed traces of experiment runs and evaluations directly in the Phoenix UI for debugging and performance analysis.\n\n资料来源：[js/packages/phoenix-client/README.md:30-60]()\n\n## Related Documentation\n\n- [Phoenix OTEL Package](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-otel/README.md) - OpenTelemetry instrumentation\n- [Phoenix Client](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md) - Python/TypeScript client libraries\n- [Phoenix Config](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md) - Environment variable configuration\n\n---\n\n\n\n## OpenTelemetry Integration\n\n### 相关页面\n\n相关主题：[Tracing System](#page-tracing-system), [Python SDK (arize-phoenix-client)](#page-python-sdk)\n\n\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [packages/phoenix-otel/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-otel/README.md)\n- [js/packages/phoenix-otel/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-otel/README.md)\n- [js/packages/phoenix-otel/src/register.ts](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-otel/src/register.ts)\n- [src/phoenix/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/__init__.py)\n- [app/src/components/project/Integrations.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/Integrations.tsx)\n- [app/src/pages/project/integrationRegistry.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/integrationRegistry.tsx)\n\n\n# OpenTelemetry Integration\n\n## Overview\n\nOpenTelemetry Integration in Phoenix provides a standardized approach to instrumenting AI applications for observability. Phoenix offers OpenTelemetry (OTel) wrappers for both Python and TypeScript/JavaScript environments, enabling developers to capture traces, spans, and telemetry data from their AI-powered applications.\n\nThe integration serves as a bridge between AI frameworks (LangChain, LlamaIndex, OpenAI, etc.) and Phoenix's observability platform, automatically collecting and forwarding telemetry data with minimal configuration.\n\n资料来源：[packages/phoenix-otel/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-otel/README.md)\n\n## Architecture\n\n### High-Level Architecture\n\n```mermaid\ngraph TD\n A[AI Application] --> B[OpenInference Instrumentations]\n B --> C[Phoenix OTEL Wrapper]\n C --> D[OTLP Exporter]\n D --> E[Phoenix Collector]\n E --> F[Phoenix Server]\n \n G[LangChain] --> B\n H[LlamaIndex] --> B\n I[OpenAI] --> B\n J[Haystack] --> B\n```\n\n### Component Stack\n\n| Layer | Python Package | TypeScript Package |\n|-------|----------------|-------------------|\n| Core Wrapper | `arize-phoenix-otel` | `@arizeai/phoenix-otel` |\n| Instrumentation | `openinference-instrumentation-*` | `@arizeai/openinference-instrumentation-*` |\n| Configuration | `phoenix.otel.register()` | `register()` |\n| Exporter | OTLP | OTLP |\n\n资料来源：[js/packages/phoenix-otel/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-otel/README.md)\n\n## Python Integration\n\n### Installation\n\n```bash\npip install arize-phoenix-otel\n```\n\nFor specific framework instrumentation:\n\n```bash\npip install openinference-instrumentation-openai\npip install openinference-instrumentation-langchain\npip install openinference-instrumentation-llama-index\n```\n\n资料来源：[packages/phoenix-otel/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-otel/README.md)\n\n### Core Module: `phoenix.otel`\n\nThe Python package exposes the `register()` function as the primary entry point for configuring OpenTelemetry tracing.\n\n#### Registration Function\n\n```python\nfrom phoenix.otel import register\n\n# Basic setup\ntracer_provider = register()\n\n# Production configuration\ntracer_provider = register(\n project_name=\"my-production-app\",\n auto_instrument=True,\n batch=True,\n api_key=\"your-api-key\",\n endpoint=\"https://app.phoenix.arize.com/s/your-space\"\n)\n```\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `PHOENIX_COLLECTOR_ENDPOINT` | OTel collector endpoint URL |\n| `PHOENIX_PROJECT_NAME` | Default project name for traces |\n| `PHOENIX_CLIENT_HEADERS` | JSON-encoded custom headers |\n| `PHOENIX_API_KEY` | Authentication API key |\n| `PHOENIX_HOST` | Phoenix server host URL |\n| `PHOENIX_PORT` | Phoenix HTTP port |\n| `PHOENIX_GRPC_PORT` | Phoenix gRPC port |\n\n资料来源：[js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n\n### Legacy Module Migration\n\nThe legacy `phoenix.trace.*` instrumentor modules have been removed. The migration path is:\n\n```python\n# Old (removed)\nfrom phoenix.trace.openai import OpenAIInstrumentor\n\n# New approach\nfrom phoenix.otel import register\nfrom openinference.instrumentation.openai import OpenAIInstrumentor\n\ntracer_provider = register()\nOpenAIInstrumentor().instrument(tracer_provider=tracer_provider)\n```\n\n资料来源：[src/phoenix/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/__init__.py)\n\n## TypeScript/JavaScript Integration\n\n### Installation\n\n```bash\nnpm install @arizeai/phoenix-otel\n# or\npnpm add @arizeai/phoenix-otel\n```\n\n资料来源：[js/packages/phoenix-otel/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-otel/README.md)\n\n### Registration Function\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\n\n// Basic setup\nconst provider = register({\n projectName: \"my-app\",\n});\n\n// Production setup with Phoenix Cloud\nconst provider = register({\n projectName: \"my-app\",\n url: \"https://app.phoenix.arize.com\",\n apiKey: process.env.PHOENIX_API_KEY,\n});\n```\n\n资料来源：[js/packages/phoenix-otel/src/register.ts](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-otel/src/register.ts)\n\n### Configuration Options\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `projectName` | `string` | `\"default\"` | Project name for organizing traces |\n| `url` | `string` | `\"http://localhost:6006\"` | Phoenix instance URL |\n| `apiKey` | `string` | `undefined` | API key for authentication |\n| `headers` | `Record` | `{}` | Custom headers for OTLP requests |\n| `batch` | `boolean` | `true` | Use batch span processing |\n| `instrumentations` | `Instrumentation[]` | `undefined` | OpenTelemetry instrumentations to register |\n| `global` | `boolean` | `true` | Register as global tracer provider |\n| `diagLogLevel` | `DiagLogLevel` | depends on NODE_ENV | Diagnostic logging level |\n\n资料来源：[js/packages/phoenix-otel/src/register.ts](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-otel/src/register.ts)\n\n### Non-Global Provider Usage\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\n\nconst provider = register({\n projectName: \"my-app\",\n global: false,\n});\n\n// Use the provider explicitly\nconst tracer = provider.getTracer(\"my-tracer\");\n```\n\n## Supported Integrations\n\n### Framework Integrations\n\nPhoenix supports tracing for the following AI frameworks through OpenInference instrumentation:\n\n| Framework | Python Package | TypeScript Package |\n|-----------|----------------|-------------------|\n| OpenAI | `openinference-instrumentation-openai` | `@arizeai/openinference-instrumentation-openai` |\n| LangChain | `openinference-instrumentation-langchain` | `@arizeai/openinference-instrumentation-langchain` |\n| LlamaIndex | `openinference-instrumentation-llama-index` | `@arizeai/openinference-instrumentation-llama-index` |\n| Haystack | `openinference-instrumentation-haystack` | N/A |\n| OpenLLMetry | `openinference-instrumentation-openllmetry` | N/A |\n\n资料来源：[app/src/components/project/Integrations.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/Integrations.tsx)\n\n### Python Setup Example\n\n```python\nfrom phoenix.otel import register\nfrom openinference.instrumentation.openai import OpenAIInstrumentor\n\ntracer_provider = register()\nOpenAIInstrumentor().instrument(tracer_provider=tracer_provider)\n```\n\n### TypeScript Setup Example\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\nimport { OpenAIInstrumentor } from \"@arizeai/openinference-instrumentation-openai\";\n\nconst provider = register();\nawait OpenAIInstrumentor().instrument();\n```\n\n## Tracing Helpers\n\n### TypeScript Tracing Utilities\n\nThe `@arizeai/phoenix-otel` package re-exports OpenInference helpers for GenAI patterns:\n\n```typescript\nimport {\n observe,\n traceAgent,\n traceChain,\n traceTool,\n withSpan,\n setAttributes,\n setMetadata,\n} from \"@arizeai/phoenix-otel\";\n```\n\n#### Example: traceChain\n\n```typescript\nimport { register, traceChain } from \"@arizeai/phoenix-otel\";\n\nconst provider = register({\n projectName: \"my-app\",\n});\n\nconst answerQuestion = traceChain(\n async (question: string) => `Handled: ${question}`,\n { name: \"answer-question\" }\n);\n\nawait answerQuestion(\"What is Phoenix?\");\nawait provider.shutdown();\n```\n\n#### Example: traceTool\n\n```typescript\nimport { traceTool } from \"@arizeai/phoenix-otel\";\n\nconst searchTool = traceTool(\n async (query: string) => {\n // Tool implementation\n return searchResults;\n },\n {\n name: \"web-search\",\n description: \"Search the web for information\",\n }\n);\n```\n\n资料来源：[js/packages/phoenix-otel/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-otel/README.md)\n\n## Configuration Flow\n\n### Setup Flow\n\n```mermaid\nsequenceDiagram\n participant Dev as Developer\n participant App as Application\n participant Phoenix as Phoenix OTEL\n participant OTel as OpenTelemetry\n participant Collector as Phoenix Collector\n\n Dev->>App: Configure environment variables\n App->>Phoenix: Call register()\n Phoenix->>OTel: Initialize TracerProvider\n OTel->>OTel: Configure BatchSpanProcessor\n OTel->>Collector: Setup OTLP Exporter\n Collector-->>App: Ready to receive traces\n App->>Collector: Send spans via OTLP\n```\n\n### Environment-Based Configuration\n\n1. **Local Development**: No configuration needed, defaults to `http://localhost:6006`\n\n```bash\n# Optional: Explicit local endpoint\nexport PHOENIX_COLLECTOR_ENDPOINT=\"http://localhost:6006\"\n```\n\n2. **Phoenix Cloud**: Configure cloud endpoint and authentication\n\n```bash\nexport PHOENIX_COLLECTOR_ENDPOINT=\"https://app.phoenix.arize.com/s/your-space\"\nexport PHOENIX_API_KEY=\"your-api-key\"\nexport PHOENIX_PROJECT_NAME=\"my-project\"\n```\n\n3. **Self-Hosted**: Point to custom deployment\n\n```bash\nexport PHOENIX_COLLECTOR_ENDPOINT=\"https://your-phoenix.example.com\"\nexport PHOENIX_API_KEY=\"your-api-key\"\n```\n\n## Best Practices\n\n### Production Recommendations\n\n| Setting | Recommendation | Reason |\n|---------|----------------|--------|\n| `batch` | `true` | Reduces network overhead with batch processing |\n| `global` | `true` | Ensures all instrumented libraries use same provider |\n| API Key | Required | Secure authentication with Phoenix Cloud |\n| Endpoint | HTTPS | Secure data transmission |\n\n### Zero Code Changes Approach\n\nFor automatic instrumentation:\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\n\n// Enable auto_instrument to automatically trace AI/ML libraries\nconst provider = register({\n auto_instrument: true,\n projectName: \"my-production-app\",\n});\n```\n\n## CLI Integration\n\nThe Phoenix CLI provides commands for working with traces:\n\n```bash\n# List recent traces\npx trace list --limit 10\n\n# Save traces to directory\npx trace list ./my-traces --limit 50\n\n# Filter by time\npx trace list --last-n-minutes 60 --limit 20\npx trace list --since 2024-01-13T10:00:00Z\n```\n\n| Option | Description |\n|--------|-------------|\n| `-n, --limit ` | Number of traces (newest first) |\n| `--last-n-minutes ` | Only traces from the last N minutes |\n| `--since ` | Traces since ISO timestamp |\n| `--format raw` | Pipe-friendly compact JSON |\n\n资料来源：[js/packages/phoenix-cli/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-cli/README.md)\n\n## Quick Reference\n\n### Python\n\n```python\nfrom phoenix.otel import register\n\n# Simple setup\nprovider = register()\n\n# With auto-instrumentation\nprovider = register(auto_instrument=True)\n\n# Production\nprovider = register(\n project_name=\"production\",\n auto_instrument=True,\n batch=True,\n api_key=\"your-key\",\n endpoint=\"https://app.phoenix.arize.com/s/your-space\"\n)\n```\n\n### TypeScript\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\n\n// Simple setup\nconst provider = register();\n\n// Production\nregister({\n projectName: \"production\",\n url: \"https://app.phoenix.arize.com\",\n apiKey: process.env.PHOENIX_API_KEY,\n});\n```\n\n## Additional Resources\n\n- [Phoenix OTEL Documentation](https://phoenix.readthedocs.io/projects/otel/en/latest/index.html)\n- [OpenInference Repository](https://github.com/Arize-ai/openinference)\n- [Phoenix Tracing Skill for Coding Agents](https://github.com/Arize-ai/phoenix/tree/main/.agents/skills/phoenix-tracing)\n\n---\n\n\n\n## Evaluation System (Phoenix Evals)\n\n### 相关页面\n\n相关主题：[Datasets and Experiments](#page-datasets-experiments), [Python SDK (arize-phoenix-client)](#page-python-sdk)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/phoenix-evals/pyproject.toml](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-evals/pyproject.toml)\n- [prompts/classification_evaluator_configs](https://github.com/Arize-ai/phoenix/blob/main/prompts/classification_evaluator_configs)\n- [js/packages/phoenix-evals/src/llm/createCorrectnessEvaluator.ts](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/src/llm/createCorrectnessEvaluator.ts)\n- [js/packages/phoenix-evals/src/llm/createFaithfulnessEvaluator.ts](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/src/llm/createFaithfulnessEvaluator.ts)\n- [src/phoenix/server/api/helpers/evaluators.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/helpers/evaluators.py)\n\n\n# Evaluation System (Phoenix Evals)\n\n## Overview\n\nPhoenix Evals is a comprehensive evaluation framework that provides **lightweight, composable building blocks** for writing and running evaluations on LLM applications. It enables developers to assess AI application quality through automated evaluators that measure hallucination detection, relevance scoring, toxicity, correctness, and other custom classification tasks.\n\n资料来源：[packages/phoenix-evals/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-evals/README.md)\n\n### Key Capabilities\n\n| Feature | Description |\n|---------|-------------|\n| **Multi-SDK Support** | Works with OpenAI, LiteLLM, LangChain, Anthropic via adapters |\n| **Input Mapping** | Powerful binding for complex data structures |\n| **Pre-built Metrics** | Hallucination detection, relevance, toxicity, correctness |\n| **OpenTelemetry Integration** | Evaluators are natively instrumented for observability |\n| **High Performance** | Up to 20x speedup with built-in concurrency and batching |\n| **Cross-platform** | Available in both Python (`arize-phoenix-evals`) and TypeScript (`@arizeai/phoenix-evals`) |\n\n资料来源：[packages/phoenix-evals/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-evals/README.md)\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n A[User Application] --> B[Phoenix Evals Core]\n B --> C[LLM Adapters]\n B --> D[Evaluator Templates]\n B --> E[Prompt Templates]\n \n C --> F[OpenAI Adapter]\n C --> G[Anthropic Adapter]\n C --> H[LiteLLM Adapter]\n C --> I[LangChain Adapter]\n \n D --> J[Correctness Evaluator]\n D --> K[Faithfulness Evaluator]\n D --> L[Relevance Evaluator]\n D --> M[Toxicity Evaluator]\n D --> N[Custom Classifier]\n \n E --> O[Hallucination Prompts]\n E --> P[Classification Prompts]\n \n B --> Q[OpenTelemetry Traces]\n```\n\n### Evaluator Types\n\nPhoenix Evals provides two primary evaluator categories:\n\n1. **Correctness Evaluator** - Assesses whether an answer correctly addresses a query based on reference context\n2. **Faithfulness Evaluator** - Determines if an answer is faithful to the provided reference text (hallucination detection)\n\n资料来源：[js/packages/phoenix-evals/src/llm/createCorrectnessEvaluator.ts](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/src/llm/createCorrectnessEvaluator.ts)\n资料来源：[js/packages/phoenix-evals/src/llm/createFaithfulnessEvaluator.ts](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/src/llm/createFaithfulnessEvaluator.ts)\n\n## Installation\n\n### Python Package\n\n```bash\npip install arize-phoenix-evals\n```\n\n资料来源：[packages/phoenix-evals/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-evals/README.md)\n\n### TypeScript Package\n\n```bash\n# npm\nnpm install @arizeai/phoenix-evals\n\n# or yarn, pnpm, bun\nyarn add @arizeai/phoenix-evals\npnpm add @arizeai/phoenix-evals\nbun add @arizeai/phoenix-evals\n```\n\n资料来源：[js/packages/phoenix-evals/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/README.md)\n\n## Creating Evaluators\n\n### TypeScript: Correctness Evaluator\n\n```typescript\nimport { createClassifier } from \"@arizeai/phoenix-evals/llm\";\nimport { openai } from \"@ai-sdk/openai\";\n\nconst model = openai(\"gpt-4o-mini\");\n\nconst promptTemplate = `\nIn this task, you will be presented with a query, a reference text and an answer. The answer is\ngenerated to the question based on the reference text. The answer may contain false information. You\nmust use the reference text to determine if the answer to the question contains false information.\n`;\n\nconst classifier = createClassifier({\n model,\n promptTemplate,\n});\n```\n\n资料来源：[js/packages/phoenix-evals/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/README.md)\n\n### TypeScript: Faithfulness Evaluator\n\nThe faithfulness evaluator detects hallucinations by comparing an answer against reference context.\n\n```typescript\nimport { createFaithfulnessEvaluator } from \"@arizeai/phoenix-evals/llm\";\nimport { openai } from \"@ai-sdk/openai\";\n\nconst evaluator = createFaithfulnessEvaluator({\n model: openai(\"gpt-4o-mini\"),\n});\n```\n\n资料来源：[js/packages/phoenix-evals/src/llm/createFaithfulnessEvaluator.ts](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/src/llm/createFaithfulnessEvaluator.ts)\n\n### Python: Using the Client API\n\nThe Phoenix server provides evaluator helpers for running evaluations programmatically:\n\n```python\nfrom phoenix.server.api.helpers.evaluators import (\n build_hallucination_evaluator,\n build_correctness_evaluator,\n)\n```\n\n资料来源：[src/phoenix/server/api/helpers/evaluators.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/helpers/evaluators.py)\n\n## Prompt Templates\n\n### Classification Evaluator Configurations\n\nPhoenix Evals uses structured prompt templates for classification tasks. The system supports multiple evaluator configurations stored in the `prompts/classification_evaluator_configs` directory.\n\n资料来源：[prompts/classification_evaluator_configs](https://github.com/Arize-ai/phoenix/blob/main/prompts/classification_evaluator_configs)\n\n### Available Evaluators on Server\n\n| Evaluator | Purpose | Input Fields |\n|-----------|---------|--------------|\n| `hallucination_evaluator` | Detects false information in answers | query, reference, response |\n| `correctness_evaluator` | Assesses answer correctness | query, reference, response |\n| `answer_relevance_evaluator` | Measures relevance of response to query | query, response |\n| `context_relevance_evaluator` | Measures relevance of context to query | query, context |\n\n资料来源：[src/phoenix/server/api/helpers/evaluators.py:1-100](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/helpers/evaluators.py)\n\n## Evaluator Configuration Schema\n\n### Project Dependencies\n\nThe Python package defines its dependencies in `pyproject.toml`:\n\n```toml\n[project]\nname = \"arize-phoenix-evals\"\nversion = \"5.0.0\"\n```\n\n**Core Dependencies:**\n- `anthropic` - Anthropic API client\n- `httpx` - HTTP client\n- `joblib` - Parallel execution\n- `litellm` - Unified LLM interface\n- `openai` - OpenAI API client\n- `tqdm` - Progress bars\n\n**Optional Dependencies:**\n- `langchain` / `langchain-core` - LangChain integration\n- `langsmith` - Tracing support\n\n资料来源：[packages/phoenix-evals/pyproject.toml](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-evals/pyproject.toml)\n\n## Evaluation Workflow\n\n```mermaid\ngraph LR\n A[Input Data] --> B[Evaluator Selection]\n B --> C[Prompt Template]\n C --> D[LLM Adapter]\n D --> E[Model Inference]\n E --> F[Response Parsing]\n F --> G[Evaluation Result]\n \n H[Reference Context] --> C\n I[Query] --> C\n```\n\n## Running Evaluations\n\n### Batch Evaluation with Concurrency\n\nPhoenix Evals supports concurrent evaluation for high performance:\n\n```python\nfrom phoenix.evals import run_evaluation\n\nresults = run_evaluation(\n model=my_model,\n evaluators=[correctness_evaluator, faithfulness_evaluator],\n data=evaluation_dataset,\n concurrency=10, # Up to 20x speedup\n)\n```\n\n### Exporting Results\n\nEvaluation results can be:\n1. Logged to Phoenix for visualization\n2. Exported as JSON/CSV\n3. Stored in datasets for future reference\n\n## Integration with Phoenix Observability\n\nEvaluators are **natively instrumented** via OpenTelemetry tracing, enabling:\n\n- Trace-level annotations for evaluation results\n- Correlation between evaluations and application spans\n- Dataset curation from production traces\n\n资料来源：[packages/phoenix-evals/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-evals/README.md)\n\n## Configuration Reference\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `PHOENIX_HOST` | Phoenix server URL | `http://localhost:6006` |\n| `PHOENIX_API_KEY` | Authentication key | — |\n| `PHOENIX_PROJECT` | Default project name | — |\n\n### Evaluator Options\n\n```typescript\ninterface EvaluatorConfig {\n model: any; // LLM model instance\n promptTemplate?: string; // Custom prompt template\n temperature?: number; // Model temperature (default: 0.0)\n maxTokens?: number; // Max tokens for response\n batchSize?: number; // Batch size for evaluation\n}\n```\n\n## Advanced Usage\n\n### Custom Classifier\n\nCreate custom binary or multi-class classification evaluators:\n\n```typescript\nimport { createClassifier } from \"@arizeai/phoenix-evals/llm\";\n\nconst customClassifier = createClassifier({\n model: myModel,\n promptTemplate: myCustomTemplate,\n labels: [\"positive\", \"negative\", \"neutral\"],\n});\n```\n\n### LangChain Integration\n\nFor LangChain applications, use the pre-built evaluations:\n\n```bash\nnpm run pre_built_evals # Uses built-in correctness evaluator\nnpm run custom_evals # Uses custom rubric with specific LLM\n```\n\n资料来源：[js/examples/apps/langchain-quickstart/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/examples/apps/langchain-quickstart/README.md)\n\n## Performance Considerations\n\n| Optimization | Expected Improvement |\n|--------------|---------------------|\n| Concurrent execution | Up to 20x speedup |\n| Batch processing | Reduced API overhead |\n| Streaming responses | Lower latency perception |\n\n## Best Practices\n\n1. **Use reference contexts** - Always provide ground truth or reference data for accurate evaluation\n2. **Configure appropriate models** - Use capable models (GPT-4 class) for accurate classification\n3. **Monitor evaluation traces** - Review flagged evaluations in Phoenix UI\n4. **Iterate on prompts** - Fine-tune prompt templates for domain-specific accuracy\n5. **Set low temperature** - Use temperature=0 for deterministic evaluation results\n\n## Related Documentation\n\n- [Phoenix Evals Documentation](https://arize-ai.github.io/phoenix/)\n- [Python Client Reference](https://arize-ai.readthedocs.io/projects/evals/en/latest/index.html)\n- [TypeScript Client Reference](https://arize-ai.github.io/phoenix/)\n- [API Reference Guide](../api_reference/README.md)\n\n---\n\n\n\n## Datasets and Experiments\n\n### 相关页面\n\n相关主题：[Evaluation System (Phoenix Evals)](#page-evals-system), [Database Models and Migrations](#page-database-models)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/phoenix/db/insertion/dataset.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/insertion/dataset.py)\n- [src/phoenix/server/api/input_types/CreateDatasetInput.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/input_types/CreateDatasetInput.py)\n- [src/phoenix/server/api/input_types/AddExamplesToDatasetInput.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/input_types/AddExamplesToDatasetInput.py)\n- [src/phoenix/db/insertion/document_annotation.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/insertion/document_annotation.py)\n- [packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py)\n- [js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n- [packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/README.md)\n- [js/examples/apps/phoenix-experiment-runner/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/examples/apps/phoenix-experiment-runner/README.md)\n- [js/examples/apps/langchain-quickstart/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/examples/apps/langchain-quickstart/README.md)\n\n\n# Datasets and Experiments\n\nPhoenix provides a comprehensive **Datasets and Experiments** system that enables users to create structured collections of examples, run evaluation tasks against them, and track results over time. This feature is designed for benchmarking models, evaluating LLM outputs, and building evaluation pipelines.\n\n## Overview\n\nDatasets in Phoenix are structured containers that hold examples used for experimentation and evaluation. Each example consists of an `input`, an `output`, and optional `metadata`. Experiments allow you to define tasks that process these examples and evaluators that score the results.\n\n```mermaid\ngraph TD\n A[Dataset] --> B[Example 1]\n A --> C[Example 2]\n A --> D[Example N]\n B --> E[input]\n B --> F[output]\n B --> G[metadata]\n E --> H[Task Function]\n F --> H\n H --> I[Evaluators]\n I --> J[Experiment Results]\n J --> K[Annotations on Traces]\n```\n\n## Core Concepts\n\n### Dataset Structure\n\nA **Dataset** is a named collection of examples with the following properties:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `name` | `str` | Unique identifier for the dataset |\n| `description` | `str` | Human-readable description |\n| `examples` | `List[Example]` | Collection of examples |\n| `version` | `int` | Dataset version for tracking changes |\n| `created_at` | `datetime` | Creation timestamp |\n\n### Example Schema\n\nEach **Example** within a dataset follows this structure:\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `input` | `dict` | Yes | Input data for the task (e.g., prompts, questions) |\n| `output` | `dict` | Yes | Expected or reference output |\n| `metadata` | `dict` | No | Additional context, tags, or auxiliary data |\n\n```python\n# Example structure\nexample = {\n \"input\": {\"question\": \"What is the capital of France?\"},\n \"output\": {\"answer\": \"Paris\"},\n \"metadata\": {\"category\": \"geography\", \"difficulty\": \"easy\"}\n}\n```\n\n资料来源：[js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n\n### Experiment Workflow\n\nThe typical experiment workflow involves:\n\n1. **Creating a Dataset** - Define and populate a dataset with examples\n2. **Defining a Task** - Create a function that processes each example\n3. **Configuring Evaluators** - Set up scoring/evaluation functions\n4. **Running the Experiment** - Execute tasks across all examples\n5. **Analyzing Results** - Review scores and export results\n\n```mermaid\ngraph LR\n A1[Create Dataset] --> B[Define Task Function]\n B --> C[Configure Evaluators]\n C --> D[Run Experiment]\n D --> E[Results + Annotations]\n E --> F[Analyze & Iterate]\n```\n\n资料来源：[js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n\n## Python Client API\n\n### Dataset Resource\n\nThe Python client provides a `Datasets` resource class for managing datasets programmatically.\n\n```python\nfrom phoenix.client import Client\n\nclient = Client()\n\n# Get an existing dataset\ndataset = client.datasets.get_dataset(\n dataset=\"my-dataset-name\",\n version_id=\"optional-version-id\" # Optional: specific version\n)\n```\n\n#### Key Methods\n\n| Method | Description |\n|--------|-------------|\n| `get_dataset()` | Retrieve a dataset by name or ID |\n| `create_dataset()` | Create a new dataset with examples |\n| `add_examples()` | Add examples to an existing dataset |\n| `upsert_dataset()` | Create or update a dataset |\n| `get_dataset_columns()` | Get column information for the dataset |\n\n资料来源：[packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py)\n\n### Creating Datasets\n\n```python\nfrom phoenix.client import Client\n\nclient = Client()\n\n# Create a dataset with examples\ndataset = client.datasets.create_dataset(\n name=\"qa-dataset\",\n description=\"Questions and answers for evaluation\",\n input_keys=[\"question\"],\n output_keys=[\"answer\"],\n metadata_keys=[\"category\", \"difficulty\"],\n inputs=[\n {\"question\": \"What is the capital of France?\"},\n {\"question\": \"What is the capital of the USA?\"}\n ],\n outputs=[\n {\"answer\": \"Paris\"},\n {\"answer\": \"Washington D.C.\"}\n ],\n metadata=[\n {\"category\": \"geography\", \"difficulty\": \"easy\"},\n {\"category\": \"geography\", \"difficulty\": \"easy\"}\n ]\n)\n```\n\n### Adding Examples to Datasets\n\n```python\n# Add more examples to an existing dataset\nawait client.datasets.add_examples(\n dataset_id=\"dataset-uuid\",\n examples=[\n {\n \"input\": {\"question\": \"What is 2 + 2?\"},\n \"output\": {\"answer\": \"4\"},\n \"metadata\": {\"category\": \"math\", \"difficulty\": \"easy\"}\n }\n ]\n)\n```\n\n#### Parameters for `add_examples`\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `dataset_id` | `str` | Yes | Dataset identifier |\n| `examples` | `List[dict]` | Yes | List of example objects |\n| `split` | `str` | No | Assign all examples to a split |\n| `timeout` | `int` | No | Request timeout in seconds |\n\n资料来源：[packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py)\n\n## TypeScript/JavaScript Client API\n\n### Creating Datasets\n\n```typescript\nimport { createDataset } from \"@arizeai/phoenix-client/datasets\";\n\nconst { datasetId } = await createDataset({\n name: \"questions\",\n description: \"a simple dataset of questions\",\n examples: [\n {\n input: { question: \"What is the capital of France\" },\n output: { answer: \"Paris\" },\n metadata: {},\n },\n {\n input: { question: \"What is the capital of the USA\" },\n output: { answer: \"Washington D.C.\" },\n metadata: {},\n },\n ],\n});\n```\n\n资料来源：[js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n\n### Running Experiments\n\n```typescript\nimport { \n asExperimentEvaluator, \n runExperiment \n} from \"@arizeai/phoenix-client/experiments\";\n\n// Define a task to run on each example\nconst task = async (example) => `hello ${example.input.name}`;\n\n// Define evaluators\nconst evaluators = [\n asExperimentEvaluator({\n name: \"matches\",\n kind: \"CODE\",\n evaluate: async ({ output, expected }) => {\n return output === expected;\n },\n }),\n];\n\n// Run the experiment\nconst results = await runExperiment({\n datasetId,\n task,\n evaluators,\n});\n```\n\n资料来源：[js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n\n## Experiment Evaluators\n\nEvaluators are functions that assess the quality of task outputs against expected results.\n\n### Evaluator Types\n\n| Kind | Description | Use Case |\n|------|-------------|----------|\n| `CODE` | Custom code-based evaluation | Exact match, regex patterns |\n| `LLM` | LLM-as-judge evaluation | Semantic similarity, relevance |\n| `BUILT_IN` | Pre-built Phoenix evaluators | Common metrics like accuracy |\n\n### Built-in Evaluators\n\nPhoenix provides pre-built evaluators for common evaluation tasks:\n\n```typescript\nimport { \n asExperimentEvaluator,\n runExperiment,\n createBuiltInEvaluator \n} from \"@arizeai/phoenix-client/experiments\";\n\n// Use a built-in correctness evaluator\nconst correctnessEval = createBuiltInEvaluator({\n name: \"correctness\",\n rubric: \"Evaluate if the response correctly answers the question\",\n});\n\nconst evaluators = [correctnessEval];\n\nconst results = await runExperiment({\n datasetId,\n task,\n evaluators,\n});\n```\n\n资料来源：[js/examples/apps/langchain-quickstart/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/examples/apps/langchain-quickstart/README.md)\n\n## Example Apps\n\n### Phoenix Experiment Runner\n\nA complete example application demonstrating dataset and experiment workflows:\n\n```bash\n# Setup requirements\npnpm install\npnpm -r build\n\n# Run the app\npnpm dev\n```\n\nFeatures:\n- Loads datasets from CSV files\n- Configures custom task functions\n- Runs experiments with multiple evaluators\n- Stores results in Phoenix\n\n资料来源：[js/examples/apps/phoenix-experiment-runner/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/examples/apps/phoenix-experiment-runner/README.md)\n\n### LangChain Integration\n\nThe LangChain quickstart demonstrates how to:\n\n1. Instrument LangChain agents with Phoenix\n2. Run correctness evaluations on agent outputs\n3. Log annotations back to Phoenix traces\n\n```typescript\n// Fetch spans and run evaluation\nconst spans = await client.spans.get_spans_dataframe({\n project_identifier: \"my-llm-app\",\n limit: 100,\n});\n\n// Run built-in correctness evaluator\nconst evalResults = await runBuiltInEvaluator({\n name: \"correctness\",\n spans,\n rubric: \"travel_rubric\",\n});\n\n// Log annotations back to Phoenix\nawait client.spans.add_span_annotations(evalResults);\n```\n\n资料来源：[js/examples/apps/langchain-quickstart/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/examples/apps/langchain-quickstart/README.md)\n\n## API Input Types\n\n### CreateDatasetInput\n\nThe server-side input type for creating datasets:\n\n```python\nclass CreateDatasetInput:\n name: str # Required: unique dataset name\n description: Optional[str] # Optional: dataset description\n metadata: Optional[dict] # Optional: dataset-level metadata\n```\n\n### AddExamplesToDatasetInput\n\n```python\nclass AddExamplesToDatasetInput:\n dataset_id: GlobalID # Required: target dataset\n examples: List[ExampleInput] # Required: examples to add\n split: Optional[str] # Optional: assign to split\n```\n\n资料来源：[src/phoenix/server/api/input_types/CreateDatasetInput.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/input_types/CreateDatasetInput.py)\n资料来源：[src/phoenix/server/api/input_types/AddExamplesToDatasetInput.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/input_types/AddExamplesToDatasetInput.py)\n\n## Database Operations\n\nDataset insertion is handled by the database layer:\n\n```python\n# In src/phoenix/db/insertion/dataset.py\nasync def insert_dataset(\n session: AsyncSession,\n dataset: Dataset,\n examples: List[Example]\n) -> None:\n # Handles dataset creation and example insertion\n # Supports batch operations for performance\n```\n\n资料来源：[src/phoenix/db/insertion/dataset.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/insertion/dataset.py)\n\n## UI Integration\n\n### Experiment Code Dialog\n\nThe Phoenix UI provides a code generation dialog for running experiments:\n\n```tsx\n\n```\n\nThis component generates:\n1. Installation commands for `arize-phoenix-client`\n2. Base URL configuration\n3. Dataset retrieval code\n4. Experiment execution examples\n\n资料来源：[app/src/components/experiment/RunExperimentCodeDialog.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/experiment/RunExperimentCodeDialog.tsx)\n\n### Python Project Guide\n\nThe UI also provides setup instructions for Python-based experiments:\n\n```tsx\n\n```\n\n资料来源：[app/src/components/project/PythonProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/PythonProjectGuide.tsx)\n\n## Authentication\n\nWhen using datasets and experiments with authentication enabled:\n\n| Environment Variable | Description |\n|---------------------|-------------|\n| `PHOENIX_API_KEY` | API key for authentication |\n| `Authorization` | Bearer token for REST/GraphQL APIs |\n| `OTEL_EXPORTER_OTLP_HEADERS` | Headers for OpenTelemetry SDKs |\n\n```bash\n# Set API key\nexport PHOENIX_API_KEY=\"your-api-key\"\n\n# Or for OTEL\nexport OTEL_EXPORTER_OTLP_HEADERS=\"Authorization=Bearer your-token\"\n```\n\n资料来源：[app/src/components/auth/OneTimeAPIKeyDialog.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/auth/OneTimeAPIKeyDialog.tsx)\n\n## Summary\n\nThe Datasets and Experiments system in Phoenix provides:\n\n- **Structured Data Management**: Create, version, and manage datasets with examples\n- **Flexible Evaluation**: Support for code-based, LLM-based, and built-in evaluators\n- **Multi-Language Support**: Python and TypeScript/JavaScript clients\n- **Trace Integration**: Results and annotations can be linked to spans\n- **Workflow Automation**: Script-based and programmatic experiment execution\n\nThis system enables teams to systematically evaluate LLM applications, track performance over time, and build automated quality assurance pipelines.\n\n---\n\n\n\n## Database Models and Migrations\n\n### 相关页面\n\n相关主题：[Server API and GraphQL](#page-server-api), [Tracing System](#page-tracing-system)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/phoenix/db/models.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/models.py)\n- [src/phoenix/db/migrations/versions/cf03bd6bae1d_init.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/migrations/versions/cf03bd6bae1d_init.py)\n- [src/phoenix/db/engines.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/engines.py)\n- [src/phoenix/db/bulk_inserter.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/bulk_inserter.py)\n- [src/phoenix/db/README.md](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/README.md)\n\n\n# Database Models and Migrations\n\nPhoenix uses SQLAlchemy ORM for database abstraction and Alembic for managing schema migrations. This document covers the database architecture, available models, migration system, engine configuration, and bulk data insertion utilities.\n\n---\n\n## Overview\n\nThe `src/phoenix/db` module is responsible for all database interactions within Phoenix. It handles:\n\n- **ORM Models**: Python class representations of database tables\n- **Migrations**: Schema version control using Alembic\n- **Engine Management**: Database connection pooling and configuration\n- **Bulk Operations**: High-performance data ingestion for trace and evaluation data\n\n资料来源：[src/phoenix/db/README.md]()\n\n---\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Phoenix Application] --> B[db Module]\n B --> C[models.py ORM Models]\n B --> D[engines.py Connection Engines]\n B --> E[bulk_inserter.py Data Import]\n B --> F[migrations/ Alembic Versions]\n \n C --> G[(SQLite PostgreSQL)]\n D --> G\n E --> G\n F -.->|applies| G\n```\n\n---\n\n## Database Engines\n\nThe `engines.py` module manages database connections. Phoenix supports both **SQLite** (default for local development) and **PostgreSQL** (recommended for production).\n\n### Key Configuration Options\n\n| Parameter | Environment Variable | Default | Description |\n|-----------|---------------------|---------|-------------|\n| Database URL | `PHOENIX_SQL_DATABASE_URL` | SQLite in temp dir | Full SQLAlchemy connection string |\n| Timeout | `PHOENIX_SQL_DATABASE_TIMEOUT` | 10 seconds | Connection/query timeout |\n\n### Supported Databases\n\n| Database | Driver | Use Case |\n|----------|--------|----------|\n| SQLite | `sqlite:///:memory:` or file path | Local development, testing |\n| PostgreSQL | `postgresql+asyncpg://` | Production deployments |\n\n资料来源：[src/phoenix/db/engines.py]()\n\n---\n\n## ORM Models\n\nThe `models.py` file defines all SQLAlchemy ORM models used by Phoenix. These models represent core entities such as projects, traces, spans, datasets, and evaluations.\n\n### Core Entities\n\n| Model | Purpose |\n|-------|---------|\n| `Project` | Container for related traces and experiments |\n| `Trace` | A single execution trace from an LLM application |\n| `Span` | Individual operation within a trace (LLM call, retrieval, tool execution) |\n| `Dataset` | Collection of evaluation test cases |\n| `DatasetExample` | Individual test case within a dataset |\n| `Evaluation` | Result of running an evaluator against a trace or span |\n| `Prompt` | Versioned prompt template |\n| `PromptVersion` | Specific version of a prompt |\n\n### Model Relationships\n\n```mermaid\ngraph LR\n A[Project] -->|1:N| B[Trace]\n B -->|1:N| C[Span]\n C -->|1:N| D[SpanAnnotation]\n B -->|1:N| E[TraceAnnotation]\n C -->|1:N| F[Evaluation]\n```\n\n资料来源：[src/phoenix/db/models.py]()\n\n---\n\n## Migrations\n\nPhoenix uses **Alembic** for database migrations, enabling schema evolution across versions without data loss.\n\n### Migration Workflow\n\n```mermaid\ngraph LR\n A[Create Migration] --> B[Test Migration]\n B --> C[Apply Migration alembic upgrade head]\n C --> D[Verify Schema]\n D --> E[Deploy]\n \n F[Rollback] --> G[alembic downgrade revision-id]\n G --> D\n```\n\n### Manual Migration Process\n\nWhen manual migration is required (e.g., recovering from a failed migration):\n\n```bash\n# Clone repository\ngit clone https://github.com/Arize-ai/phoenix.git\ncd phoenix/src/phoenix/db\n\n# Set database URL if using non-default\nexport PHOENIX_SQL_DATABASE_URL=\n\n# Apply migrations forward\nalembic upgrade head\n\n# Rollback if needed (⚠️ can cause data loss)\nalembic downgrade \n```\n\n资料来源：[src/phoenix/db/README.md]()\n\n### Migration File Structure\n\n```\nmigrations/\n└── versions/\n ├── cf03bd6bae1d_init.py # Initial schema\n ├── a1b2c3d4e5f6_next.py # Subsequent migrations\n └── ...\n```\n\n资料来源：[src/phoenix/db/migrations/versions/cf03bd6bae1d_init.py]()\n\n### Automatic Migration Application\n\nMigrations are applied automatically when the Phoenix application starts. The application connects to the database and runs any pending migrations before serving requests.\n\n---\n\n## Bulk Inserter\n\nThe `bulk_inserter.py` module provides high-performance batch import functionality for large volumes of trace and evaluation data.\n\n### Purpose\n\n- Efficiently import thousands of spans and traces in a single transaction\n- Reduce database round-trips through batch operations\n- Support bulk annotation and evaluation data ingestion\n\n### Key Features\n\n| Feature | Description |\n|---------|-------------|\n| Batch Processing | Inserts records in configurable batch sizes |\n| Transaction Management | Commits atomically to ensure data consistency |\n| Error Handling | Rollback support for failed batches |\n\n资料来源：[src/phoenix/db/bulk_inserter.py]()\n\n---\n\n## Environment Configuration\n\n### Database Configuration Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `PHOENIX_SQL_DATABASE_URL` | No | SQLite | Database connection string |\n| `PHOENIX_SQL_DATABASE_TIMEOUT` | No | 10 | Query timeout in seconds |\n\n### Example Configurations\n\n**Local Development (SQLite):**\n```bash\n# Uses default SQLite in temporary directory\nphoenix serve\n```\n\n**Production (PostgreSQL):**\n```bash\nexport PHOENIX_SQL_DATABASE_URL=\"postgresql+asyncpg://user:password@localhost:5432/phoenix\"\nphoenix serve\n```\n\n---\n\n## Initialization Schema\n\nThe initial migration (`cf03bd6bae1d_init.py`) establishes the core database schema including:\n\n- Projects and traces tables\n- Spans with parent-child relationships\n- Annotation tables for traces and spans\n- Dataset and evaluation tables\n- Prompt versioning tables\n\n资料来源：[src/phoenix/db/migrations/versions/cf03bd6bae1d_init.py]()\n\n---\n\n## Summary\n\n| Component | Technology | Purpose |\n|-----------|------------|---------|\n| ORM | SQLAlchemy | Python-to-SQL mapping |\n| Migrations | Alembic | Schema version control |\n| Engines | SQLAlchemy async engines | Connection management |\n| Bulk Insert | Custom batch utilities | High-volume data import |\n| Databases | SQLite, PostgreSQL | Persistence backends |\n\n---\n\n\n\n## Frontend Application\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture), [Server API and GraphQL](#page-server-api)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [app/src/pages/project/OnboardingSteps.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/OnboardingSteps.tsx)\n- [app/src/components/agent/DocsToolDetails.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/agent/DocsToolDetails.tsx)\n- [app/src/components/project/TypeScriptProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/TypeScriptProjectGuide.tsx)\n- [app/src/pages/example/ExampleExperimentRunsTable.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/example/ExampleExperimentRunsTable.tsx)\n- [app/src/pages/project/ProjectTracesPage.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/ProjectTracesPage.tsx)\n- [app/src/Routes.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/Routes.tsx)\n- [app/src/components/project/PythonProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/PythonProjectGuide.tsx)\n- [app/src/pages/trace/DocumentItem.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/trace/DocumentItem.tsx)\n- [app/src/components/trace/AnnotationConfigList.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/trace/AnnotationConfigList.tsx)\n- [app/src/components/core/icon/Icons.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/core/icon/Icons.tsx)\n- [app/src/components/markdown/streamdownComponents.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/markdown/streamdownComponents.tsx)\n\n\n# Frontend Application\n\n## Overview\n\nThe Phoenix Frontend Application is a React-based web interface that provides observability, tracing, and evaluation capabilities for AI applications. It serves as the primary user interface for interacting with Phoenix's backend services, enabling users to manage projects, visualize traces, configure annotations, and evaluate LLM outputs.\n\nThe frontend is built with modern React patterns including hooks, context providers, and component composition. It integrates with `@arizeai/phoenix-otel` for telemetry data collection and `@arizeai/phoenix-evals` for evaluation functionality.\n\n资料来源：[app/src/pages/project/ProjectTracesPage.tsx:1-50]()\n\n## Architecture Overview\n\n### Component Hierarchy\n\n```mermaid\ngraph TD\n A[App] --> B[Routes]\n B --> C[ProjectTracesPage]\n B --> D[Playground]\n B --> E[Settings Pages]\n C --> F[TracesTable]\n C --> G[SpanFiltersProvider]\n D --> H[PromptMenu]\n E --> I[AnnotationConfigList]\n \n F --> J[AnnotationLabel]\n J --> K[AnnotationTooltip]\n \n G --> L[TracePaginationProvider]\n L --> M[TracingRoot]\n```\n\n### Technology Stack\n\n| Layer | Technology | Purpose |\n|-------|------------|---------|\n| Framework | React 19+ | UI rendering |\n| Routing | React Router v6 | SPA navigation |\n| State | React Context + Hooks | State management |\n| Styling | CSS-in-JS (Fela) | Component styling |\n| Icons | Custom SVG Components | UI iconography |\n| Tables | @tanstack/react-table | Data tables |\n| Forms | Adobe React Spectrum | Form components |\n\n资料来源：[app/src/Routes.tsx:1-100]()\n\n## Routing Structure\n\nThe application uses React Router for navigation with a nested route structure supporting breadcrumbs and lazy loading.\n\n### Main Routes\n\n| Route | Component | Purpose |\n|-------|-----------|---------|\n| `/projects/:projectId/traces` | `ProjectTracesPage` | Trace visualization |\n| `/projects/:projectId/traces/:traceId` | `TraceTree` | Single trace view |\n| `/settings/*` | `SettingsPage` | Application settings |\n| `/playground` | `Playground` | LLM prompt playground |\n\n```typescript\n// Routes structure excerpt\n}>\n } />\n } />\n } />\n } />\n } />\n } />\n } />\n } />\n\n```\n\n资料来源：[app/src/Routes.tsx:30-80]()\n\n## Core Components\n\n### Tracing Components\n\n#### ProjectTracesPage\n\nThe main container for trace visualization, wrapping content in context providers for tracing state management.\n\n```typescript\nexport const ProjectTracesPage = () => {\n const { tracesQueryReference } = useProjectPageQueryReferenceContext();\n\n return (\n \n \n \n }>\n \n \n \n \n \n \n \n \n );\n};\n```\n\n资料来源：[app/src/pages/project/ProjectTracesPage.tsx:40-65]()\n\n#### TracesTable\n\nDisplays experiment runs and traces in a paginated, sortable table format. Integrates with `useReactTable` from TanStack Table for efficient rendering.\n\n| Feature | Implementation |\n|---------|----------------|\n| Pagination | Custom pagination with fetch on scroll |\n| Sorting | Column-based sorting |\n| Selection | Row selection for batch operations |\n| Navigation | Click to view trace details |\n\n资料来源：[app/src/pages/example/ExampleExperimentRunsTable.tsx:1-100]()\n\n### Project Setup Components\n\n#### OnboardingSteps\n\nProvides step-by-step guidance for integrating applications with Phoenix. Supports multiple programming languages and package managers.\n\n```typescript\nexport function OnboardingSteps({\n language,\n packages,\n implementationCode,\n docsHref,\n githubHref,\n generatedApiKey,\n onApiKeyGenerated,\n extraEnvVars,\n}: {\n language: ProgrammingLanguage;\n packages: readonly string[];\n implementationCode: string;\n // ... additional props\n}) {\n const isHosted = IS_HOSTED_DEPLOYMENT;\n const isAuthEnabled = window.Config.authenticationEnabled;\n // ...\n}\n```\n\n资料来源：[app/src/pages/project/OnboardingSteps.tsx:50-85]()\n\n#### TypeScriptProjectGuide\n\nLanguage-specific setup guide for TypeScript/JavaScript projects with OTEL initialization code generation.\n\n```typescript\n\n```\n\n#### PythonProjectGuide\n\nSimilar component for Python projects using `arize-phoenix-otel` package.\n\n| Package | Purpose |\n|---------|---------|\n| `arize-phoenix-otel` | OpenTelemetry instrumentation for Python |\n| `opentelemetry-*` | Standard OTEL packages |\n\n资料来源：[app/src/components/project/PythonProjectGuide.tsx:1-60]()\n\n### Document and Annotation Components\n\n#### DocumentItem\n\nRenders document metadata and annotations within trace views. Supports JSON display and annotation overlay.\n\n```typescript\n\n {JSON.stringify(metadata)}\n\n\n```\n\n资料来源：[app/src/pages/trace/DocumentItem.tsx:1-80]()\n\n#### AnnotationConfigList\n\nDropdown component for selecting annotation configurations. Displays annotation names with color swatches and type tokens.\n\n```typescript\n\n }\n trailingContent={\n {annotationType?.toLocaleLowerCase()}\n }\n>\n {name}\n\n```\n\n资料来源：[app/src/components/trace/AnnotationConfigList.tsx:1-50]()\n\n### Markdown Rendering\n\n#### streamdownComponents\n\nCustom React components for rendering markdown content with Phoenix-specific styling.\n\n| Component | Element | Styling |\n|-----------|---------|---------|\n| `blockquote` | `