# @arizeai/openinference-core 中文文档

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

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

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

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

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

- 包体积（解压后）：1.3 MB，285 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2024-08-20T00:31:58.041Z
- 最新版本发布：2026-10-23T22:15:28.833Z
- 近 30 天下载量：1375863（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：42（近 12 个月 25 个）

## 中文简介

OpenInference Core提供所有OpenInference SDK包共享的公用设施.

## 安装

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

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

## README

# 打开推论核心

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

`@arizeai/openinference-core` 是OpenInform JS软件包的共同追踪基础。 它规定:

-   上下文属性传播( e)`session.id`, (中文(简体) ), `user.id`、元数据、标记、即时模板)
-   跨度包装( o)`withSpan`, (中文(简体) ), `traceChain`, (中文(简体) ), `traceAgent`, (中文(简体) ), `traceTool`(中文(简体) )
-   方法装饰器追踪(`@observe`(中文(简体) )
-   lLM/检索/嵌入/工具以及注释/评价属性的助手
-   通过可选的敏感数据遮盖 `OITracer` 跟踪配置

## 安装

```bash
npm install @arizeai/openinference-core

# Only needed if you want to run the Quick Start example in this README:
npm install @arizeai/openinference-semantic-conventions @opentelemetry/sdk-trace-node @opentelemetry/resources
```

## 快速启动( 可启动)

此示例的导出跨度为 stdout并设置了 OpenInference 项目名 .

```typescript
import {
  OpenInferenceSpanKind,
  SEMRESATTRS_PROJECT_NAME,
} from "@arizeai/openinference-semantic-conventions";
import {
  ConsoleSpanExporter,
  NodeTracerProvider,
  SimpleSpanProcessor,
} from "@opentelemetry/sdk-trace-node";
import { resourceFromAttributes } from "@opentelemetry/resources";

import { withSpan } from "@arizeai/openinference-core";

const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    [SEMRESATTRS_PROJECT_NAME]: "openinference-core-demo",
  }),
  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
});

provider.register();

const answerQuestion = withSpan(
  async (question: string) => {
    return `Answer: ${question}`;
  },
  {
    name: "answer-question",
    kind: OpenInferenceSpanKind.CHAIN,
  },
);

async function main() {
  const answer = await answerQuestion("What is OpenInference?");
  console.log(answer);
}

void main();
```

## 背景属性

每个设置器返回一个新的 OpenTeleometry 上下文 。 编译以传播请求级别属性 :

-   `setSession(context, { sessionId })`
-   `setUser(context, { userId })`
-   `setMetadata(context, metadataObject)`
-   `setTags(context, string[])`
-   `setPromptTemplate(context, { template, variables?, version? })`
-   `setAttributes(context, attributes)`

```typescript
import { context } from "@opentelemetry/api";
import {
  setAttributes,
  setMetadata,
  setPromptTemplate,
  setSession,
  setTags,
  setUser,
} from "@arizeai/openinference-core";

let ctx = context.active();
ctx = setSession(ctx, { sessionId: "sess-42" });
ctx = setUser(ctx, { userId: "user-7" });
ctx = setMetadata(ctx, { tenant: "acme", environment: "prod" });
ctx = setTags(ctx, ["support", "priority-high"]);
ctx = setPromptTemplate(ctx, {
  template: "Answer using docs about {topic}",
  variables: { topic: "billing" },
  version: "v3",
});
ctx = setAttributes(ctx, { "app.request_id": "req-123" });

context.with(ctx, async () => {
  // spans started in this context by openinference-core wrappers
  // include these propagated attributes automatically
});
```

如果您使用平面的 OpenTelemetry 跟踪器手动创建跨度, 请明确应用所传播的属性 :

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

const tracer = trace.getTracer("manual-tracer");
const span = tracer.startSpan("manual-span");
span.setAttributes(getAttributesFromContext(context.active()));
span.end();
```

## 函数包装器

### `withSpan`

```typescript
import { OpenInferenceSpanKind } from "@arizeai/openinference-semantic-conventions";
import { withSpan } from "@arizeai/openinference-core";

const retrieve = withSpan(
  async (query: string) => {
    return [`Document for ${query}`];
  },
  {
    name: "retrieve-documents",
    kind: OpenInferenceSpanKind.RETRIEVER,
  },
);
```

### `traceChain`, (中文(简体) ), `traceAgent`, (中文(简体) ), `traceTool`,还有朋友

这些包裹呼叫 `withSpan` 设置 `kind` 自动。 每一次都有一个 开源词跨度类型( O)`traceLLM`, (中文(简体) ), `traceRetriever`, (中文(简体) ), `traceReranker`, (中文(简体) ), `traceEmbedding`, (中文(简体) ), `traceGuardrail`, (中文(简体) ), `traceEvaluator`, (中文(简体) ), `tracePrompt`, (中文(简体) ), `traceDecision`) (中文(简体) ).

```typescript
import { traceAgent, traceChain, traceTool } from "@arizeai/openinference-core";

const tracedChain = traceChain(async (q: string) => `chain result: ${q}`, {
  name: "rag-chain",
});

const tracedTool = traceTool(async (city: string) => ({ temp: 72, city }), {
  name: "weather-tool",
});

const tracedAgent = traceAgent(
  async (q: string) => {
    const toolResult = await tracedTool("seattle");
    return tracedChain(`${q} (${toolResult.temp}F)`);
  },
  { name: "qa-agent" },
);
```

### 自定义输入/输出处理器

```typescript
import { getInputAttributes, getRetrieverAttributes, withSpan } from "@arizeai/openinference-core";

const retriever = withSpan(async (query: string) => [`Doc A for ${query}`, `Doc B for ${query}`], {
  name: "retriever",
  kind: "RETRIEVER",
  processInput: (query) => getInputAttributes(query),
  processOutput: (documents) =>
    getRetrieverAttributes({
      documents: documents.map((content, i) => ({
        id: `doc-${i}`,
        content,
      })),
    }),
});
```

## 装饰者`@observe`(中文(简体) )

`observe` 将分类方法与跟踪和保存方法相包装 `this` 上下文. 应用时使用类型脚本 5+ 标准装饰器 `@observe`。 。 。 .

```typescript
import { OpenInferenceSpanKind } from "@arizeai/openinference-semantic-conventions";
import { observe } from "@arizeai/openinference-core";

class ChatService {
  @observe({ kind: OpenInferenceSpanKind.CHAIN })
  async runWorkflow(message: string) {
    return `processed: ${message}`;
  }

  @observe({ name: "llm-call", kind: OpenInferenceSpanKind.LLM })
  async callModel(prompt: string) {
    return `model output for: ${prompt}`;
  }
}
```

## 属性助手 API

使用这些助手生成 OpenInference 兼容属性并附加到相间 :

-   `getLLMAttributes({ provider, modelName, inputMessages, outputMessages, tokenCount, tools, ... })`
-   `getDecisionAttributes({ provider, system, modelName, requestModelName, responseModelName, tokenCount })`
-   `getEmbeddingAttributes({ modelName, embeddings })`
-   `getRetrieverAttributes({ documents })`
-   `getAnnotationAttributes({ annotations, scope? })`
-   `getEvaluationAttributes({ evaluations, scope? })`
-   `getToolAttributes({ name, description?, parameters })`
-   `getMetadataAttributes(metadataObject)`
-   `getInputAttributes(input)` 编号 : `getOutputAttributes(output)`
-   `defaultProcessInput(...args)` 编号 : `defaultProcessOutput(result)`

示例

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

const tracer = trace.getTracer("llm-service");

tracer.startActiveSpan("llm-inference", (span) => {
  span.setAttributes(
    getLLMAttributes({
      provider: "openai",
      modelName: "gpt-4o-mini",
      inputMessages: [{ role: "user", content: "What is OpenInference?" }],
      outputMessages: [{ role: "assistant", content: "OpenInference is..." }],
      tokenCount: { prompt: 12, completion: 44, total: 56 },
      invocationParameters: { temperature: 0.2 },
    }),
  );
  span.end();
});
```

## 跟踪配置和编辑`OITracer`(中文(简体) )

`OITracer` 将 OpenTeleometry 跟踪器包裹起来, 并可以在写入间隔前修改或删除敏感属性 :

```typescript
import { trace } from "@opentelemetry/api";
import { OpenInferenceSpanKind } from "@arizeai/openinference-semantic-conventions";
import { OITracer, withSpan } from "@arizeai/openinference-core";

const tracer = new OITracer({
  tracer: trace.getTracer("my-service"),
  traceConfig: {
    hideInputs: true,
    hideOutputText: true,
    hideEmbeddingVectors: true,
    base64ImageMaxLength: 8_000,
  },
});

const traced = withSpan(async (prompt: string) => `model response for ${prompt}`, {
  tracer,
  kind: OpenInferenceSpanKind.LLM,
  name: "safe-llm-call",
});
```

您也可以配置环境变量的掩码 :

-   `OPENINFERENCE_HIDE_LLM_TOOLS`
-   `OPENINFERENCE_HIDE_INPUTS`
-   `OPENINFERENCE_HIDE_OUTPUTS`
-   `OPENINFERENCE_HIDE_INPUT_MESSAGES`
-   `OPENINFERENCE_HIDE_OUTPUT_MESSAGES`
-   `OPENINFERENCE_HIDE_INPUT_IMAGES`
-   `OPENINFERENCE_HIDE_INPUT_TEXT`
-   `OPENINFERENCE_HIDE_OUTPUT_TEXT`
-   `OPENINFERENCE_HIDE_EMBEDDING_VECTORS`
-   `OPENINFERENCE_BASE64_IMAGE_MAX_LENGTH`
-   `OPENINFERENCE_HIDE_PROMPTS`

## 辅助工具

-   `withSafety({ fn, onError? })`: 包围一个函数并返回 `null` 错误
-   `safelyJSONStringify(value)` 编号 : `safelyJSONParse(value)`守卫JSON行动

## 节点模块中的文档和源代码

一旦你安装了开源核心软件包, 你已经有了完整的 内部本地可用的开源核心文档和源代码 节点 模块. 您的编码代理可以直接读取这些内容 — 没有网络访问 所需经费.

```
node_modules/@arizeai/openinference-core/src/              # Full source code organized by module
node_modules/@arizeai/openinference-core/docs/             # Official documentation with examples
```

这意味着你的代理人可以查询准确的 API 签名,执行,和 直接从安装的软件包中使用示例 -- -- 确保它总是使用 实际安装在您的项目中的 SDK 版本 .

## 文档

-   API 参考 : [@ arizeai/ openinference- core](https://arize-ai.github.io/openinference/js/modules/_arizeai_openinference-core.html)
-   OpenInformation JS 文件: [开放式推论/js](https://arize-ai.github.io/openinference/js/)
-   源代码 : [js/包装/开放核心](https://github.com/Arize-ai/openinference/tree/main/js/packages/openinference-core)

## 常见问题

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

OpenInference Core提供所有OpenInference SDK包共享的公用设施\.

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

在项目目录运行 npm install @arizeai/openinference-core，或使用 pnpm add / yarn add / bun add。

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

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

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

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

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

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

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

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

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

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