@arizeai/凤凰客户端

此软件包提供了一个 TypeScript 客户端 阿里兹·凤凰 API (英语). 它仍在积极发展之中,并可能发生变化.

安装

# or yarn, pnpm, bun, etc...
npm install @arizeai/phoenix-client

配置

如果有的话,客户端会自动读取环境变量.

使用了下列环境变量:

• PHOENIX_ENDPOINT -你的凤凰城的地基URL 这是给客户设定的.
• PHOENIX_API_KEY - 用于认证的 API 密钥 .
• PHOENIX_CLIENT_HEADERS - 在所有请求中添加自定义信头。 JSON 字符串对象 .
• PHOENIX_COLLECTOR_ENDPOINT - 由OTel SDK读取以进行微量导出,通常与 URL 相同 PHOENIX_ENDPOINT。当 PHOENIX_ENDPOINT 未设定.

PHOENIX_ENDPOINT='http://localhost:12345' PHOENIX_API_KEY='xxxxxx' pnpx tsx examples/list_datasets.ts
# emits the following request:
# GET http://localhost:12345/v1/datasets
# headers: {
#   "Authorization": "Bearer xxxxxx",
# }

或者,您可以直接将配置选项传递给客户端,这些选项将优先于环境变量和默认值.

const phoenix = createClient({
  options: {
    baseUrl: "http://localhost:6006",
    headers: {
      Authorization: "Bearer xxxxxx",
    },
  },
});

对于过期的证书,创建认证的获取执行 并传递给客户。 令牌提供者控制存储和刷新 旋转 收到的请求 401 共享一个刷新操作 复试一回.

import { createAuthFetch, createClient } from "@arizeai/phoenix-client";

const authFetch = createAuthFetch({
  getAccessToken: async ({ forceRefresh }) => {
    if (forceRefresh) {
      await refreshAndPersistTokens();
    }
    return loadTokens().accessToken;
  },
});

const phoenix = createClient({
  options: {
    baseUrl: "http://localhost:6006",
    fetch: authFetch,
  },
});

提示

@arizeai/phoenix-client 页:1 prompts 输出会暴露公用事业公司与LLMs合作的提示.

创建提示并推向凤凰城

这个 createPrompt 函数可用于在凤凰城创建用于版本控制和再利用的提示.

import { createPrompt, promptVersion } from "@arizeai/phoenix-client/prompts";

const version = createPrompt({
  name: "my-prompt",
  description: "test-description",
  version: promptVersion({
    description: "version description here",
    modelProvider: "OPENAI",
    modelName: "gpt-3.5-turbo",
    template: [
      {
        role: "user",
        content: "{{ question }}",
      },
    ],
    invocationParameters: {
      temperature: 0.8,
    },
  }),
});

被推到凤凰城的提示被版本并可以被标记.

从凤凰城拉出快讯

这个 getPrompt 函数可用于根据 Phoenix 的一些“快速识别符”从 Phoenix 中拉出一个提示并返回到 Phoenix SDK Expoon 类型.

import { getPrompt } from "@arizeai/phoenix-client/prompts";

const prompt = await getPrompt({ name: "my-prompt" });
// ^ you now have a strongly-typed prompt object, in the Phoenix SDK Prompt type

const promptByTag = await getPrompt({ tag: "production", name: "my-prompt" });
// ^ you can optionally specify a tag to filter by

const promptByVersionId = await getPrompt({
  versionId: "1234567890",
});
// ^ you can optionally specify a prompt version Id to filter by

使用带有 LLM 提供者 SDK 的 Phoenix 提示

这个 toSDK 帮助器功能可用于将 Phoenix Express转换为 LLM 提供者 SDK 所期望的格式. 然后,您可以使用 LLM 提供者 SDK 作为正常的, 用您的快取 .

如果你的提示在凤凰城保存为 openai,可以使用 toSDK 函数可以将提示转换为OpenAI,甚至Anthropic和Vercel AI SDK所期望的格式。 我们会尽力的 工作转换为您所选择的 LLM 提供者 SDK .

支持下列LLM供应商SDK:

• Vercel AI SDK: (中文(简体) ) ai 页:1
• 打开AI : openai 打开 (v6和v7) (中文(简体) )
• 安东尼: anthropic @ 慈善- ai/ sdk

说明: 这些提供者 SDK 是可选的对等依赖性 — 安装 @arizeai/phoenix-client 不拉他们进来。 安装您转换到自己的一个, 例如 . npm install ai, (中文(简体) ), npm install openai,或 npm install @anthropic-ai/sdk调用 toSDK({ sdk: "ai" | "openai" | "anthropic" }) 未安装匹配的 SDK 在运行时失败 .

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { getPrompt, toSDK } from "@arizeai/phoenix-client/prompts";

const prompt = await getPrompt({ name: "my-prompt" });
const promptAsAI = toSDK({
  sdk: "ai",
  // ^ the SDK you want to convert the prompt to, supported SDKs are listed above
  variables: {
    "my-variable": "my-value",
  },
  // ^ you can format the prompt with variables, if the prompt has any variables in its template
  //   the format (Mustache, F-string, etc.) is specified in the Prompt itself
  prompt,
});
// ^ promptAsAI is now in the format expected by the Vercel AI SDK generateText function

const response = await generateText({
  model: openai(prompt.model_name),
  // ^ the model adapter provided by the Vercel AI SDK can be swapped out for any other model
  //   adapter supported by the Vercel AI SDK. Take care to use the correct model name for the
  //   LLM provider you are using.
  ...promptAsAI,
});

REST 终点

客户端为定义于 凤凰城 OpenAPI 光谱。 。 。 .

端点通过强类型的字符串字元和TypeScript自动完成客户对象内部可以访问.

import { createClient } from "@arizeai/phoenix-client";

const phoenix = createClient();

// Get all datasets
const datasets = await phoenix.GET("/v1/datasets");

// Get specific prompt
const prompt = await phoenix.GET("/v1/prompts/{prompt_identifier}/latest", {
  params: {
    path: {
      prompt_identifier: "my-prompt",
    },
  },
});

凤凰城内的OpenAPI取景器或 凤凰城 OpenAPI 光谱。 。 。 .

数据集

这个 @arizeai/phoenix-client 软件包允许您创建和管理数据集,这些数据集是用于实验和评价的实例集.

创建数据集

您可以通过提供名称、描述和一系列实例来创建数据集(每个实例都有) input, (中文(简体) ), output选择 metadata) (中文(简体) ).

import { createDataset } from "@arizeai/phoenix-client/datasets";

const { datasetId } = await createDataset({
  name: "questions",
  description: "a simple dataset of questions",
  examples: [
    {
      input: { question: "What is the capital of France" },
      output: { answer: "Paris" },
      metadata: {},
    },
    {
      input: { question: "What is the capital of the USA" },
      output: { answer: "Washington D.C." },
      metadata: {},
    },
  ],
});
// You can now use datasetId to run experiments or add more examples

管理分割

使用 createDatasetSplit, (中文(简体) ), updateDatasetSplit,以及 deleteDatasetSplit 以创建、编辑和删除在现有数据集上的拆分(例如训练和测试子集)并添加或删除示例。 这些帮助者需要凤凰城服务器QQ 19.20.

import {
  createDatasetSplit,
  deleteDatasetSplit,
  updateDatasetSplit,
} from "@arizeai/phoenix-client/datasets";

const dataset = { datasetName: "questions" };

const testSplit = await createDatasetSplit({
  dataset,
  name: "test",
  exampleIds: ["example-1"], // example ids or nodeIds from getDatasetExamples
});

await updateDatasetSplit({
  dataset,
  splitId: testSplit.id,
  addExampleIds: ["example-2"],
  removeExampleIds: ["example-1"],
});

// Removes the split and its memberships, not the examples
await deleteDatasetSplit({ dataset, splitId: testSplit.id });

见 数据集参考 用于所有参数和服务器版本注释.

实验

这个 @arizeai/phoenix-client 软件包提供了用于运行和评价数据集任务的实验 API。 这对于制定基准模型、评价产出和跟踪凤凰城的实验结果很有用.

运行一个实验

要进行实验,你通常:

1. 创建数据集( 或使用已有的数据集)
2. 定义要运行在每个实例上的任务函数
3. 定义一名或多名评价员对产出进行评分或标签
4. 运行实验并检查结果

下面是一个完整的例子:

import { createDataset } from "@arizeai/phoenix-client/datasets";
import {
  asExperimentEvaluator,
  runExperiment,
} from "@arizeai/phoenix-client/experiments";

// 1. Create a dataset
const { datasetId } = await createDataset({
  name: "names-dataset",
  description: "a simple dataset of names",
  examples: [
    {
      input: { name: "John" },
      output: { text: "Hello, John!" },
      metadata: {},
    },
    {
      input: { name: "Jane" },
      output: { text: "Hello, Jane!" },
      metadata: {},
    },
  ],
});

// 2. Define a task to run on each example
const task = async (example) => `hello ${example.input.name}`;

// 3. Define evaluators
const evaluators = [
  asExperimentEvaluator({
    name: "matches",
    kind: "CODE",
    evaluate: async ({ output, expected }) => {
      const matches = output === expected?.text;
      return {
        label: matches ? "matches" : "does not match",
        score: matches ? 1 : 0,
        explanation: matches
          ? "output matches expected"
          : "output does not match expected",
        metadata: {},
      };
    },
  }),
  asExperimentEvaluator({
    name: "contains-hello",
    kind: "CODE",
    evaluate: async ({ output }) => {
      const matches = typeof output === "string" && output.includes("hello");
      return {
        label: matches ? "contains hello" : "does not contain hello",
        score: matches ? 1 : 0,
        explanation: matches
          ? "output contains hello"
          : "output does not contain hello",
        metadata: {},
      };
    },
  }),
];

// 4. Run the experiment
const experiment = await runExperiment({
  dataset: { datasetId },
  task,
  evaluators,
});

提示 : 任务和评估员使用仪器 打开几何。您可以在凤凰卫视UI中直接查看实验运行和评估的详细痕迹,用于调试和性能分析.

Eval 测试

该套件还曝光了用于写作的Vitest和Jest子模块 作为普通测试套件的数据集支持评价.

npm install -D @arizeai/phoenix-client vitest dotenv

import * as px from "@arizeai/phoenix-client/vitest";
import { expect } from "vitest";

px.describe(
  "text-to-sql",
  () => {
    px.test(
      "select all",
      {
        input: { userQuery: "Get all users" },
        expected: { sql: "SELECT * FROM users;" },
      },
      async ({ input, expected }) => {
        const sql = await generateSql(input.userQuery);
        px.logOutput({ sql });
        expect(sql).toEqual(expected?.sql);
      }
    );
  },
  {
    acceptanceCriteria: [
      // every test must pass (100% of the auto-logged `pass` boolean is true)
      {
        annotationName: "pass",
        metric: "passRate",
        passFn: (a) => a.score === true,
        minPassRate: 1,
      },
    ],
  }
);

可在可互换的三种模式中的任何一种下提供参考输出 键 - expected, (中文(简体) ), reference,或 output - 这样你就可以匹配任何名称 您的评审人员预计。 他们都决心到同一个位置: 数据集 实例 output,与评估者和测试机构接触,作为 expected。 。 。 . 一次提供多个是类型错误.

使用 @arizeai/phoenix-client/vitest/reporter 或者说 @arizeai/phoenix-client/jest/reporter 打印凤凰城数据集 试验链接、注释总量和最后的接受标准 运行。 接受标准 门的套房完成后 - average 检查一个聚合栏( 这样 CI 就可以允许平均 80% 同时运行) (每个案件) passRate 需要运行的最小分数满足 每次运行 passFn 上观相.

见 CI Eval 测试, (中文(简体) ), 维特, (中文(简体) ), 欢乐, (中文(简体) ), 财务报告和审定财务报表 说明 设置的指南,全 describe 编号 : test 编号 : test.each API,接受标准,重复, 干运行模式和注释细节.

追踪

这个 @arizeai/phoenix-client 软件包提供 traces 从凤凰城项目获取微量数据的导出.

获取追踪

使用 getTraces 以可选过滤、排序和页码来取回痕迹.

import { getTraces } from "@arizeai/phoenix-client/traces";

// Get the latest 10 traces
const result = await getTraces({
  project: { projectName: "my-project" },
  limit: 10,
});
console.log(result.data); // array of trace objects

// Filter by time range and include full span details
const detailed = await getTraces({
  project: { projectName: "my-project" },
  startTime: "2026-03-01T00:00:00Z",
  endTime: new Date(),
  includeSpans: true,
  sort: "latency_ms",
  order: "desc",
});

// Filter by session
const sessionTraces = await getTraces({
  project: { projectName: "my-project" },
  sessionId: "my-session-id",
});

// Filter by error status and latency (requires Phoenix server >= 20.12.0)
const slowFailures = await getTraces({
  project: { projectName: "my-project" },
  filter: "error_count > 0 and latency_ms >= 1000",
});

error, (中文(简体) ), minLatencyMs,以及 maxLatencyMs 已贬值,但仍支持在 服务器 QQ 20.8.0. 使用 error_count > 0 编号 : error_count == 0, (中文(简体) ), latency_ms >= N,以及 latency_ms <= N 内 filter 换句话说 空表达式不过滤; 无效 表达式返回 HTTP 400。 请求下一页时保留相同的表达式 .

倾斜

使用 cursor 从上一个结果获取下一页:

import { getTraces } from "@arizeai/phoenix-client/traces";

let cursor: string | null = null;
const allTraces = [];

do {
  const result = await getTraces({
    project: { projectName: "my-project" },
    limit: 50,
    cursor,
  });
  allTraces.push(...result.data);
  cursor = result.nextCursor ?? null;
} while (cursor);

说明: 需要凤凰城服务器 QQ 13.15.0.

追踪说明

添加结构反馈( 标签/ 按名称计分) 到整个跟踪 。 使用 addTraceAnnotation 用于一个跟踪或 logTraceAnnotations 为分批.

import {
  addTraceAnnotation,
  logTraceAnnotations,
} from "@arizeai/phoenix-client/traces";

// Single annotation
const result = await addTraceAnnotation({
  traceAnnotation: {
    traceId: "abc123",
    name: "correctness",
    label: "correct",
    score: 1.0,
    annotatorKind: "HUMAN",
  },
  sync: true, // returns { id: "..." } when sync, null when async
});

// Batch
await logTraceAnnotations({
  traceAnnotations: [
    {
      traceId: "abc123",
      name: "correctness",
      label: "correct",
      score: 1.0,
      annotatorKind: "HUMAN",
    },
    {
      traceId: "def456",
      name: "faithfulness",
      label: "faithful",
      score: 0.9,
      annotatorKind: "LLM",
    },
  ],
  sync: true,
});

保留名称 note 被拒绝 – 使用 addTraceNote 改为自由式说明(见下文).

追踪注释

注是自由格式文本的一种特殊注释类型——用于开口编码,审查者在任何标题存在之前都会在追踪上留下定性的观察. 多个音符可以在同一行迹上并存.

import { addTraceNote } from "@arizeai/phoenix-client/traces";

await addTraceNote({
  traceNote: {
    traceId: "abc123",
    note: "Needs follow-up — unexpected tool call sequence",
  },
});

说明: addTraceNote 需要凤凰城服务器 QQ 14.13.0.

西班牙语

这个 @arizeai/phoenix-client 软件包提供 spans 导出用于有强大过滤功能的查询跨度.

正在获取 Spans

使用 getSpans 按类型、状态、名称、追踪等进行过滤.

import { getSpans } from "@arizeai/phoenix-client/spans";

// Get recent spans
const result = await getSpans({
  project: { projectName: "my-project" },
  limit: 100,
});

// Filter by span kind and status
const errorLLMSpans = await getSpans({
  project: { projectName: "my-project" },
  spanKind: "LLM",
  statusCode: "ERROR",
});

// Filter by name and trace
const spans = await getSpans({
  project: { projectName: "my-project" },
  name: "chat_completion",
  traceIds: ["trace-abc", "trace-def"],
});

// Root spans only
const rootSpans = await getSpans({
  project: { projectName: "my-project" },
  parentId: null,
});

记录垃圾邮件

使用 logSpans 直接向项目提交跨度, 使用凤凰城的简化跨度结构—— 相同的形状 getSpans。这对不经过OpenTeleometry的回填或迁移跨度有用。 如果您的应用程序已经装入了 OpenTeleometry 的仪器,导出周期为 @arizeai/phoenix-otel 换句话说.

import { logSpans } from "@arizeai/phoenix-client/spans";

const result = await logSpans({
  project: { projectName: "my-project" },
  spans: [
    {
      name: "chat_completion",
      context: { trace_id: "abc123", span_id: "def456" },
      span_kind: "LLM",
      start_time: "2024-01-01T00:00:00Z",
      end_time: "2024-01-01T00:00:01Z",
      status_code: "OK",
      attributes: { "llm.model_name": "gpt-4" },
    },
  ],
});
console.log(`Queued ${result.totalQueued} of ${result.totalReceived} spans`);

如果请求中的任何跨度无效或重复已经存在的跨度,则所有跨度均不排队 logSpans 丢出一个 SpanCreationError 与 invalidSpans 财务报告和审定财务报表 duplicateSpans 细节.

扩展说明

这个 spans 导出还提供了管理跨度说明的功能——将评价、反馈和标签加入跨度.

添加单一注释

import { addSpanAnnotation } from "@arizeai/phoenix-client/spans";

const result = await addSpanAnnotation({
  spanAnnotation: {
    spanId: "f8b1c3a2d4e5f678",
    name: "correctness",
    label: "correct",
    score: 1.0,
    explanation: "The response accurately answered the question",
    annotatorKind: "HUMAN",
  },
  sync: true, // wait for the annotation ID to be returned
});
// result: { id: "annotation-id" } when sync: true, null when sync: false

日志多重说明

import { logSpanAnnotations } from "@arizeai/phoenix-client/spans";

const results = await logSpanAnnotations({
  spanAnnotations: [
    {
      spanId: "f8b1c3a2d4e5f678",
      name: "relevance",
      label: "relevant",
      score: 0.95,
      annotatorKind: "LLM",
    },
    {
      spanId: "a1b2c3d4e5f67890",
      name: "relevance",
      label: "irrelevant",
      score: 0.2,
      annotatorKind: "LLM",
    },
  ],
  sync: true,
});
// results: [{ id: "..." }, { id: "..." }]

获取 Span 说明

import { getSpanAnnotations } from "@arizeai/phoenix-client/spans";

const result = await getSpanAnnotations({
  project: { projectName: "my-project" },
  spanIds: ["f8b1c3a2d4e5f678", "a1b2c3d4e5f67890"],
  includeAnnotationNames: ["relevance", "correctness"],
  limit: 100,
});
console.log(result.data); // array of span annotation objects

会议

这个 @arizeai/phoenix-client 软件包提供 sessions 导出用于管理对话会话及其说明.

获取会话

使用 listSessions 以列出项目的所有会话,或 getSession 以 ID 获取单个会话.

import {
  listSessions,
  getSession,
  addSessionAnnotation,
  addSessionNote,
} from "@arizeai/phoenix-client/sessions";

// List all sessions for a project
const sessions = await listSessions({
  project: "my-project",
});

for (const session of sessions) {
  console.log(
    `Session: ${session.sessionId}, Traces: ${session.traces.length}`
  );
}

// Get a single session by its ID
const session = await getSession({ sessionId: "my-session-id" });
console.log(session.traces); // array of trace summaries in the session

添加会话说明

await addSessionAnnotation({
  sessionAnnotation: {
    sessionId: "my-session-id",
    name: "user-satisfaction",
    label: "satisfied",
    score: 0.9,
    annotatorKind: "HUMAN",
  },
});

添加会话说明

需要 Phoenix 服务器的会话笔记 14.17.0 或更新.

await addSessionNote({
  sessionNote: {
    sessionId: "my-session-id",
    note: "Needs review",
  },
});

项目

这个 @arizeai/phoenix-client 软件包提供 projects 用于列出项目和管理其保留政策和注释配置任务.

获取项目

使用 getProjects 以列表项目。 刺伤是为你处理的.

import { getProjects } from "@arizeai/phoenix-client/projects";

// List every project
const projects = await getProjects();

for (const project of projects) {
  console.log(`Project: ${project.name} (${project.id})`);
}

过 nameContains 以对项目名称不敏感子字符串过滤。 过滤器是应用服务器侧并需要 Phoenix 服务器 17.16.0 或更新.

const agentProjects = await getProjects({ nameContains: "agent" });

指定保留政策

使用 setProjectRetentionPolicy 通过GlobalID指定现有的痕量保留政策。 按名称或 GlobalID 选择工程 .

import { setProjectRetentionPolicy } from "@arizeai/phoenix-client/projects";

await setProjectRetentionPolicy({
  projectName: "support-bot",
  policyId: "UHJvamVjdFRyYWNlUmV0ZW50aW9uUG9saWN5OjI=",
});

过 policyId: null 将项目重置为凤凰的默认保留政策:

await setProjectRetentionPolicy({
  projectId: "UHJvamVjdDox",
  policyId: null,
});

此助手只将项目的任务更改为现行政策. 创建、读取、更新和删除保留政策不属于TypeScript项目帮助器的范围.

指定注释配置

使用 assignProjectAnnotationConfig 财务报告和审定财务报表 unassignProjectAnnotationConfig 要添加或删除单个注释配置。 按名称或GlobalID选择工程和配置。 两通电话都是一流的。 这些助手需要凤凰城服务器 17.16.0 或更新.

import {
  assignProjectAnnotationConfig,
  listProjectAnnotationConfigs,
  setProjectAnnotationConfigs,
  unassignProjectAnnotationConfig,
} from "@arizeai/phoenix-client/projects";

await assignProjectAnnotationConfig({
  projectName: "support-bot",
  configName: "correctness",
});

await unassignProjectAnnotationConfig({
  projectName: "support-bot",
  configName: "correctness",
});

使用 setProjectAnnotationConfigs 用配置 GlobalID 替换整个设置。 通过一个空列表来清除每个任务 :

const configs = await listProjectAnnotationConfigs({
  projectName: "support-bot",
});

// Keep only the categorical configs
await setProjectAnnotationConfigs({
  projectName: "support-bot",
  configIds: configs
    .filter((config) => config.type === "CATEGORICAL")
    .map((config) => config.id),
});

await setProjectAnnotationConfigs({
  projectName: "support-bot",
  configIds: [],
});

如果配置名称包含 /中选择 configId 换句话说 服务器无法路由 a / 在 URL 路径中.

秘诀

使用 secrets 原子创建、更新或删除加密的条目点 供应商证书。 字符串值创建或更新密钥,同时 null 删除它。 复制密钥使用批次中的最后一个出错 。 结果 只包含已更改的密钥名称,绝不返回密钥值.

import { upsertOrDeleteSecrets } from "@arizeai/phoenix-client/secrets";

const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) throw new Error("OPENAI_API_KEY is required");

const result = await upsertOrDeleteSecrets({
  secrets: [
    { key: "OPENAI_API_KEY", value: apiKey },
    { key: "OLD_PROVIDER_API_KEY", value: null },
  ],
});

console.log(result.upsertedKeys);
console.log(result.deletedKeys);

管理机密需要一位管理员 当凤凰城认证 启用 。 避免记录请求批次或以其他方式保留其值.

实例

要运行示例,请使用 pnpm 运行 :

pnpm install
pnpx tsx examples/list_datasets.ts
# change the file name to run other examples

兼容性

此套件使用 打开( o) 以生成来自 Phoenix OpenAPI spec 的类型.

因此,这个软件包只与 arize-phonix 服务器 8.0.0及以上.

兼容性表 :

社区

加入我们的社区,与成千上万的人工智能建设者建立联系:

• 加入我们的行列 黑社会。 。 。 .
• 读取 凤凰网文献。 。 。 .
• * 提问并提供反馈 #凤凰支持 # 频道.
• 留下一颗星星在我们身上 GitHub 图像。 。 。 .
• 报告错误 GitHub 问题。 。 。 .
• X 跟着我们 页:1。 。 。 .
• 跟着我们 链接。 。 。 .
• 看看我们 路线图 看看我们下一步要去哪儿.