# @arizeai/openinference-vercel 中文文档

规范地址：https://npmcn.com/package/%40arizeai/openinference-vercel/

版本：3\.3\.1
npm 元数据更新时间：2026-10-23T22:16:57.862Z
中文译文更新时间：2026-11-06T19:17:51.029Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40arizeai/openinference-vercel
原文对照：https://npmcn.com/package/%40arizeai/openinference-vercel/?lang=original
项目主页：https://github.com/arize-ai/openinference/tree/main/js/packages/openinference-vercel
源码仓库：https://github.com/Arize-ai/openinference

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：477 kB，64 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：6 个
- peer 依赖：ai ^7\.0\.0，@ai-sdk/otel ^1\.0\.0，@opentelemetry/api \>=1\.7\.0 \<2\.0\.0，@opentelemetry/semantic-conventions \>=1\.41\.1 \<2\.0\.0
- 首次发布：2024-08-20T22:14:05.503Z
- 最新版本发布：2026-10-23T22:16:57.485Z
- 近 30 天下载量：538129（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：59（近 12 个月 36 个）

## 中文简介

摄取 Vercel AI SDK 跨度的 OpenInference 工具

## 安装

```sh
npm install @arizeai/openinference-vercel
```

也可以使用：`pnpm add @arizeai/openinference-vercel`、`yarn add @arizeai/openinference-vercel`、`bun add @arizeai/openinference-vercel`

## README

# Open Information 虚拟

[![npm version](https://badge.fury.io/js/@arizeai%2Fopeninference-vercel.svg)](https://badge.fury.io/js/@arizeai%2Fopeninference-vercel)

这个软件包提供改造的公用事业 [维塞尔 AI SDK](https://github.com/vercel/ai) OpenTeleometry 跨入 OpenInference 跨度, 诸如平台 [调整 AX](https://arize.com/products/ax?utm_source=docs&utm_medium=web&utm_content=openinference) 财务报告和审定财务报表 [凤凰](https://phoenix.arize.com/)。 。 。 .

> 注:本包针对AI SDK v7遥测. 使用 `@arizeai/openinference-vercel` v2.x为AI SDK v6.

## AI SDK 兼容性

| AI SDK 版本 | 支助职等 | 页:1 |
| --- | --- | --- |
| v7.x (中文(简体) ) | 支助 | 用途 `@ai-sdk/otel` `OpenTelemetry`,该输出 `gen_ai.*` 默认跨度。 任择补充 `ai.*` 属性填补非GenAI数据空白. |
| v6.x及更年长 | 不支持 | 使用 `@arizeai/openinference-vercel` v2.x. 使用的AI SDK v6 `experimental_telemetry` 并射出一个不同的长相. |

AI SDK v7和这个包需要节点.js 22或更新,并且只是无害环境管理. 在升级前配置您的应用程序 .

## 安装

```shell
npm install --save @arizeai/openinference-vercel
```

您还需要 OpenTeleometry , `ai`, (中文(简体) ), `@ai-sdk/otel`,以及您使用的 AI SDK 供应商包。 以下实例 `@ai-sdk/openai`。 。 。 .

```shell
npm i @arizeai/openinference-vercel ai@^7 @ai-sdk/otel@^1 @ai-sdk/openai@^4 @opentelemetry/api @opentelemetry/exporter-trace-otlp-proto @opentelemetry/resources @opentelemetry/sdk-trace-base @opentelemetry/sdk-trace-node @opentelemetry/semantic-conventions @arizeai/openinference-semantic-conventions
```

对于部署在Vercel上的 Next.js 应用程序,也安装 `@vercel/otel`数字 :

```shell
npm i @vercel/otel
```

## 使用量

`@arizeai/openinference-vercel` 提供将AI SDK v7 遥测转换为 OpenInference 属性的跨度处理器,然后导出跨度。 要启动,请在您的应用程序中添加 OpenTeleometry, 并在应用程序启动时注册一次 AI SDK 遥测 .

对于部署在Vercel上的Next.js应用程序, `registerOTel` 从 `@vercel/otel` 仍然注册 OpenTeleometry 提供者、 资源属性、 输出方和跨度处理器 。 AI SDK v7's (英语) `registerTelemetry(new OpenTelemetry(...))` 不替换该设置;它配置了AI SDK的遥测集成.

要处理 Vercel AI SDK 跨度,请添加 `OpenInferenceSimpleSpanProcessor` 或者说 `OpenInferenceBatchSpanProcessor` 到您的 OpenTelection 配置 .

> \[注\] 这个 `OpenInferenceSpanProcessor` 不处理跨度出口本身,通过一个 [出口国](https://opentelemetry.io/docs/languages/js/exporters/) 作为参数.

### 类型脚本应用程序

对于一个单独的TypeScript或Node.js应用程序导出到凤凰城,在你的AI SDK调用运行前创建一个仪器模块并导入.

```typescript
// instrumentation.ts
import { SEMRESATTRS_PROJECT_NAME } from "@arizeai/openinference-semantic-conventions";
import {
  enrichSpanWithOpenInference,
  OpenInferenceBatchSpanProcessor,
} from "@arizeai/openinference-vercel";

import { OpenTelemetry } from "@ai-sdk/otel";
import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { Resource } from "@opentelemetry/resources";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { registerTelemetry } from "ai";

// For troubleshooting, set the log level to DiagLogLevel.DEBUG.
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.INFO);

const phoenixUrl = process.env["PHOENIX_COLLECTOR_ENDPOINT"] ?? "http://localhost:6006/v1/traces";
const phoenixApiKey = process.env["PHOENIX_API_KEY"];

export const tracerProvider = new NodeTracerProvider({
  resource: new Resource({
    [SEMRESATTRS_PROJECT_NAME]: process.env["PHOENIX_PROJECT_NAME"] ?? "my-typescript-app",
  }),
  spanProcessors: [
    new OpenInferenceBatchSpanProcessor({
      exporter: new OTLPTraceExporter({
        url: phoenixUrl,
        headers: phoenixApiKey
          ? {
              api_key: phoenixApiKey,
              Authorization: `Bearer ${phoenixApiKey}`,
            }
          : undefined,
      }),
    }),
  ],
});

tracerProvider.register();

registerTelemetry(
  new OpenTelemetry({
    enrichSpan: enrichSpanWithOpenInference,
    // Optional, but recommended for fuller OpenInference coverage.
    usage: true,
    providerMetadata: true,
    embedding: true,
    reranking: true,
    experimental_decision: true,
    runtimeContext: true,
    headers: true,
    toolChoice: true,
    schema: true,
  }),
);
```

然后在使用AI SDK之前导入仪器模块.

```typescript
import "./instrumentation";

import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";

const result = await generateText({
  model: openai("gpt-4o-mini"),
  prompt: "Write a short story about a cat.",
  // Telemetry is enabled by default once OpenTelemetry is registered.
  // Use telemetry for per-call metadata or to opt out with isEnabled: false.
  telemetry: { functionId: "story-agent" },
});
```

### Next.js 应用程序

```typescript
// instrumentation.ts
import { registerOTel } from "@vercel/otel";
import { registerTelemetry } from "ai";
import { OpenTelemetry } from "@ai-sdk/otel";
import {
  enrichSpanWithOpenInference,
  isOpenInferenceSpan,
  OpenInferenceSimpleSpanProcessor,
} from "@arizeai/openinference-vercel";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { SEMRESATTRS_PROJECT_NAME } from "@arizeai/openinference-semantic-conventions";

export function register() {
  const phoenixApiKey = process.env["PHOENIX_API_KEY"];

  registerTelemetry(
    new OpenTelemetry({
      enrichSpan: enrichSpanWithOpenInference,
      // Optional, but recommended for fuller OpenInference coverage.
      usage: true,
      providerMetadata: true,
      embedding: true,
      reranking: true,
      experimental_decision: true,
      runtimeContext: true,
      headers: true,
      toolChoice: true,
      schema: true,
    }),
  );

  registerOTel({
    serviceName: "phoenix-next-app",
    attributes: {
      // This is not required but it will ensure your traces get added to a specific project in Arize Phoenix
      [SEMRESATTRS_PROJECT_NAME]: "your-next-app",
    },
    spanProcessors: [
      new OpenInferenceSimpleSpanProcessor({
        exporter: new OTLPTraceExporter({
          headers: phoenixApiKey
            ? {
                api_key: phoenixApiKey,
                Authorization: `Bearer ${phoenixApiKey}`,
              }
            : undefined,
          url:
            process.env["PHOENIX_COLLECTOR_ENDPOINT"] ?? "https://app.phoenix.arize.com/v1/traces",
        }),
        spanFilter: (span) => {
          // Remove this filter if you want to export non-generative spans too.
          return isOpenInferenceSpan(span);
        },
      }),
    ],
  });
}
```

一次 `registerTelemetry(new OpenTelemetry())` 称为 AI SDK v7 遥测默认启用. 使用 `telemetry` 仅针对元数据, 如 `functionId` 或选择退出.

```typescript
const result = await generateText({
  model: openai("gpt-4-turbo"),
  prompt: "Write a short story about a cat.",
  telemetry: { functionId: "story-agent" },
});
```

要禁用一个呼叫的遥测, 设置 `telemetry: { isEnabled: false }`。 。 。 .

关于AI SDK v7遥测的详情,见 [AI SDK 遥测文档](https://ai-sdk.dev/docs/ai-sdk-core/telemetry)。 。 。 .

### 决策模式

AI SDK 软件 `experimental_decide` 需要打电话 `ai` 7.0.128 或晚于 `@ai-sdk/otel` 1.0.128 或以后 `experimental_decision: true` 设置于 `OpenTelemetry` 用来记录州,问答.

SDK发出一个外出操作周期和一个儿童模式呼叫周期,两者都带有相同的 `gen_ai.operation.name: "decide"`,提供者,和模型属性。 处理器不能把它们分开,所以没有 `enrichSpan` 两个跨度均导出为 `DECISION` 跨度,每个都带有模型身份,模型调用的用法归于第二个决定. 过 `enrichSpan: enrichSpanWithOpenInference` 改为 `OpenTelemetry` 将外部作业归类为 `CHAIN` 跨度(带有决定输入和输出)和模式调用为 `DECISION` 间距( 与 `decision.model_name`, (中文(简体) ), `decision.provider`, (中文(简体) ), `decision.system`,以及 `decision.token_count.*`) (中文(简体) ).

决定跨度确定以下模式: `decision.*` 而不是说 `llm.*`。为了防止下游GenAI转换器将模型重新贴上LLM的标签,处理器删除 `gen_ai.provider.name`, (中文(简体) ), `gen_ai.request.model`, (中文(简体) ), `gen_ai.response.model`,以及 `gen_ai.usage.*` 从决定的时间跨度 绘制它们。 附属于同一追踪器提供者的其他出口商在删除之后可看到时间间隔.

这个 [Jev裁决实例](https://npmcn.com/package/%40arizeai/openinference-vercel/examples/ai-sdk-decision.ts) 调用 TypeSafe 的主机模式 `@ai-sdk/typesafe-ai` 和要求 `TYPESAFE_API_KEY`。 。 。 .

关于Vercel OpenTelemotry支持的更多信息,请参见: [Vercel Open遥测指南](https://vercel.com/docs/observability/otel-overview)。 。 。 .

## 失去父母的人

当过滤到 `spanFilter: isOpenInferenceSpan`,只有AI相关的跨度是 导出。 但最高的AI跨度(例如. `ai.generateText`, (中文(简体) ), `ai.streamText`)为 经常在 a 下父化 **非AI 间距** 例如,HTTP/服务器横跨 接下来,Js父母 下方的一切。 那个父母被过滤掉,留下AI跨度 **孤儿**: 它引用了从未导出过的父程序, 因此后端可能不是 能够正确追踪.

设定 `reparentOrphanedSpans: true` 拆分(重新根制)任何直接父母的AI 是一个非AI的跨度,所以它成为了痕量根. 多个兄弟的AI跨度相同 痕量是每个被重新扎根的,人工智能跨入了人工智能的母体之下保留了自己的位置.

```typescript
new OpenInferenceSimpleSpanProcessor({
  exporter,
  spanFilter: isOpenInferenceSpan,
  reparentOrphanedSpans: true, // default: false
});
```

检查是无国籍的——从起始时间上读取父跨度,所以没有 保存每个跟踪簿记.

如果重新扎根的跨度是 `ai.*` 框架包装软件包不映射到 跨度类型(例如,在AI SDK上方的代理框架每转一转), 否则,它会是善良的 并被过滤。 这种根被标记 `openinference.span.kind = AGENT` 因此它被保存为微量根. 这与 形状(一个未识别的AI-like root),而不是任何特定框架的横跨名称.

`reparentOrphanedSpans` 正在选择( 默认) `false`) (中文(简体) ). 用于与 滤波器会降低非AI父母的长度——这正是孤儿的处境 AI儿童首先:当过滤器移除非AI父母时,每个AI跨度 它下面是指着一个从未出口过的父母。 重新创建 孩子们,所以追踪仍然。 (反之,没有这种过滤器,非AI 父程序仍然被导出, 所以对孤儿没有意义, 而复父程序只会分裂 (原始内容存档于2013-10-12). an other-intact track.)

## 宣传会话和上下文属性

Vercel AI SDK创造了自己的跨度,所以——与OpenInference仪器不同, 横跨 `OITracer` - 这个处理器确实 **没有** 读取 OpenInform 语境 。 这意味着你设定的值 [`@arizeai/openinference-core`](https://www.npmjs.com/package/@arizeai/openinference-core) 帮助者( e)`setSession`, (中文(简体) ), `setUser`, (中文(简体) ), `setMetadata`, (中文(简体) ), `setTags`永远无法到达输出的 AI 横跨。 A 类 `session.id` 绕着这样的电话, 否则会丢失:

```typescript
import { context } from "@opentelemetry/api";
import { setSession } from "@arizeai/openinference-core";

context.with(setSession(context.active(), { sessionId }), () =>
  streamText({ model, prompt, experimental_telemetry: { isEnabled: true } }),
);
```

`propagateContextAttributes` 复制启动时间的每个 OpenInference 属性 上下文(`session.id`, (中文(简体) ), `user.id`, (中文(简体) ), `metadata.*`, (中文(简体) ), `tag.tags`,...) 直接在每段时间 `onStart`,所以追踪组在阿里泽/凤凰城的会话。 默认启用; 设置 给 `false` 选择退出.

```typescript
new OpenInferenceSimpleSpanProcessor({
  exporter,
  spanFilter: isOpenInferenceSpan,
  reparentOrphanedSpans: true,
  propagateContextAttributes: true, // default: true
});
```

因为值是直接写到中间的 它们都活下来了 `reparentOrphanedSpans` 重新定位和导出,并在相同背景下开始跨度 (儿童模特/工具呼叫)继承他们.

携带GenAI的西班牙人 `gen_ai.conversation.id` 属性( 例如每个跨度) Vercel evel exits)也获得 `session.id` 从它,不需要上下文设置。 A 类 `session.id` 从上下文传播为优先.

## 常见问题

### @arizeai/openinference-vercel 是什么？

摄取 Vercel AI SDK 跨度的 OpenInference 工具

### 如何安装 @arizeai/openinference-vercel？

在项目目录运行 npm install @arizeai/openinference-vercel，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：ai（^7\.0\.0）、@ai-sdk/otel（^1\.0\.0）、@opentelemetry/api（\>=1\.7\.0 \<2\.0\.0）、@opentelemetry/semantic-conventions（\>=1\.41\.1 \<2\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @arizeai/openinference-vercel 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @arizeai/openinference-vercel 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @arizeai/openinference-vercel 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @arizeai/openinference-vercel 可以商用吗？

@arizeai/openinference-vercel 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @arizeai/openinference-vercel 的下载量有多少？

根据 npm 官方下载统计，@arizeai/openinference-vercel 在 2026/10/07 – 2026/11/05 这 30 天内被下载 538,129 次，日均约 17,938 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @arizeai/openinference-vercel 还在维护吗？

最新版本 3\.3\.1 发布于 2026/10/24（14 天前）；至今共发布 59 个版本，其中过去 12 个月发布了 36 个；首次发布于 2024/08/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。