# @eyepop\.ai/eyepop 中文文档

规范地址：https://npmcn.com/package/%40eyepop.ai/eyepop/

版本：4\.0\.0
npm 元数据更新时间：2026-11-13T20:48:57.268Z
中文译文更新时间：2026-11-14T06:35:17.857Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40eyepop.ai/eyepop
原文对照：https://npmcn.com/package/%40eyepop.ai/eyepop/?lang=original
项目主页：https://github.com/eyepop-ai/eyepop-sdk-node#readme
源码仓库：https://github.com/eyepop-ai/eyepop-sdk-node

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

- 包体积（解压后）：3.4 MB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：10 个
- 首次发布：2024-01-24T23:26:10.124Z
- 最新版本发布：2026-11-13T20:48:56.923Z
- 近 30 天下载量：3610（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：153（近 12 个月 51 个）

## 中文简介

EyePop.ai推论 API 的官方Node.js / Typescript 库

## 安装

```sh
npm install @eyepop.ai/eyepop
```

也可以使用：`pnpm add @eyepop.ai/eyepop`、`yarn add @eyepop.ai/eyepop`、`bun add @eyepop.ai/eyepop`

## README

# EyePop.ai 节点SDK

EyePop.ai节点SDK提供JavaScript和TypeScript访问EyePop工人会话进行图像和视频推断.

## 安装

### 节点

CI验证了22号节点.

```shell
npm install --save @eyepop.ai/eyepop
```

见 [节点示例](https://github.com/eyepop-ai/eyepop-sdk-node/blob/main/examples/node) 用于可运行的脚本.

### 浏览器

浏览器应用程序可以直接使用捆绑的 SDK :

```html
<script src="https://cdn.jsdelivr.net/npm/@eyepop.ai/eyepop/dist/eyepop.min.js"></script>
```

API 密钥不能用于浏览器代码 。 浏览器应用程序应该与您信任的后端创建的会话连接 .

### 原生反应

反应原生应用程序应该使用反应原生软件包:

```shell
npm install --save @eyepop.ai/react-native-eyepop
```

见 [反应本地示例](https://github.com/eyepop-ai/eyepop-sdk-node/tree/main/examples/react_native/upload-example)。 。 。 .

## 认证

SDK支持这些认证模式:

-   可信服务器侧码的 API 密钥认证 .
-   持续工人会议选择,以进行规定的部署.
-   OAuth浏览仪表板用户创建本地演示.

### 服务器- Side API 密钥

设定 `EYEPOP_API_KEY` 在您的服务器环境中。 API密钥是机密,不得在浏览器捆绑,移动应用程序捆绑,或公共寄存器中被曝光.

```shell
export EYEPOP_API_KEY=<your_api_key>
```

在构建工人端点时创建带有流行的瞬间会话 。 这让 EyePop 在媒体处理前安排正确的计算.

```typescript
import { EyePop } from '@eyepop.ai/eyepop'
;(async () => {
    const endpoint = await EyePop.workerEndpoint({
        pop: {
            components: [
                {
                    type: 'inference',
                    ability: 'eyepop.person:latest',
                    categoryName: 'person',
                },
            ],
        },
    }).connect()
    try {
        const results = await endpoint.process({ source: { path: 'examples/example.jpg' } })
        for await (const result of results) {
            console.log(result)
        }
    } finally {
        await endpoint.disconnect()
    }
})()
```

临时开庭,通过 `pop` 在尽可能创建终点时。 使用 `endpoint.changePop(pop)` 只有在一个已经连接的瞬间工人需要切换出"流行"时.

管道模式为默认,不运行工人会话; `EYEPOP_ENV=staging|production|local` 选择它的管道API。 与 `isPipelineMode: false` (或 `EYEPOP_PIPELINE_MODE=false`(没有) `sessionUuid`, SDK 创建计算会话 `POST /v1/sessions?wait=true`。 。 。 .

ModelLess CPU 流行使用相同的构造器-流行路径 :

```typescript
const endpoint = await EyePop.workerEndpoint({
    pop: {
        components: [
            {
                type: 'inference',
                ability: 'eyepop.localize-objects:latest',
                categoryName: 'objects',
                params: {
                    prompts: [{ prompt: 'person' }],
                },
            },
        ],
    },
}).connect()
```

您也可以从服务器侧配置中明确传递密钥 :

```typescript
const endpoint = await EyePop.workerEndpoint({
    apiKey: process.env.EYEPOP_API_KEY,
}).connect()
```

`accessToken` 被接受为同一无记名证书形状:

```typescript
const endpoint = await EyePop.workerEndpoint({
    accessToken: process.env.EYEPOP_ACCESS_TOKEN,
}).connect()
```

被窝住 `auth` 选项仍然被支持,但已贬值。 过 `apiKey`, (中文(简体) ), `accessToken`, (中文(简体) ), `session`,或 `oAuth2` 用于新代码的顶层.

### 常务会议

如果EyePop为您的部署提供了持续工作段, 设置 `EYEPOP_SESSION_UUID` 或通过 `sessionUuid` 明确,取消管道模式(`isPipelineMode: false`) (中文(简体) ).

```shell
export EYEPOP_API_KEY=<your_api_key>
export EYEPOP_SESSION_UUID=<your_session_uuid>
```

```typescript
import { EyePop } from '@eyepop.ai/eyepop'
;(async () => {
    const endpoint = await EyePop.workerEndpoint({
        sessionUuid: process.env.EYEPOP_SESSION_UUID,
        isPipelineMode: false,
    }).connect()

    try {
        const results = await endpoint.process({ source: { path: 'sample.mp4' } })
        for await (const result of results) {
            console.log(result)
        }
    } finally {
        await endpoint.disconnect()
    }
})()
```

持久性会话通常预设. 在这种情况下,直接处理媒体,不打电话 `changePop()` 除非你的部署是为了接受运行时间的改变.

持续的部署通过计算-api或EyePop工具生成. 例如,一个可信任的服务器可以用内置的流行创建持续部署,然后通过返回的 `session_uuid` 给SDK:

```shell
curl -sS -X POST "https://compute.eyepop.ai/v1/deployments?wait=true" \
  -H "Authorization: Bearer $EYEPOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "node-modeless-deployment",
    "pop": {
      "components": [
        {
          "type": "inference",
          "ability": "eyepop.localize-objects:latest",
          "categoryName": "objects",
          "params": {
            "prompts": [{ "prompt": "person" }]
          }
        }
      ]
    }
  }'
```

答复包括: `session_uuid`, (中文(简体) ), `session_status`, (中文(简体) ), `status_url`,以及工人访问元数据。 票价 `status_url` 直到部署达到 `pipeline_ok`,然后与 `sessionUuid`。 。 。 .

### 浏览器和移动客户端

别放 `EYEPOP_API_KEY` 在浏览器或移动应用程序代码中。 从信任的后端创建 EyePop 会话, 然后只将会话 JSON 传递给客户端 .

### 本地 Dashboard Demos 浏览器 OAuth

Dashboard 用户可以使用当前浏览器会话运行本地浏览器演示:

```html
<script>
    document.addEventListener('DOMContentLoaded', async () => {
        const endpoint = await EyePop.workerEndpoint({ oAuth2: true }).connect()
        try {
            await endpoint.changePop({
                components: [
                    {
                        type: 'inference',
                        ability: 'eyepop.person:latest',
                        categoryName: 'person',
                    },
                ],
            })
        } finally {
            await endpoint.disconnect()
        }
    })
</script>
```

## 处理媒体

### 本地文件

```typescript
const results = await endpoint.process({ source: { path: 'examples/example.jpg' } })
for await (const result of results) {
    console.log(result)
}
```

`process()` 返回一个 `AsyncIterable` 预测。 图像通常产生一个预测. 视频和动画图像容器每个帧产生一个预测.

### 可读流线

流需要明确的MIME类型 :

```typescript
import fs from 'node:fs'

const stream = fs.createReadStream('examples/example.jpg')
const results = await endpoint.process({
    source: { stream, mimeType: 'image/jpeg' },
})
```

### 公开 URL

公共HTTP(S),RTSP,和RTMP URL可以在不从应用程序上传文件的情况下进行处理.

```typescript
const results = await endpoint.process({
    source: { url: 'https://demo-eyepop-videos.s3.amazonaws.com/test1_vlog.mp4' },
})
```

### 图像组( 多个图像, 一个结果)

发送多个图像为 a **单人** 来源为流行进程 **一起行动** 作为一推断单元——例如多图像的VLM快取. 组产量 **一个** 预测整个集,不同于下面的分批,每个图像都是独立的推论.

```typescript
// Local files
const results = await endpoint.uploadGroup(['a.jpg', 'b.jpg', 'c.jpg'])
for await (const result of results) {
    console.log(result)
}

// In-memory streams (optional parallel MIME types)
import fs from 'node:fs'
import { Readable } from 'node:stream'
const stream1 = Readable.toWeb(fs.createReadStream('a.jpg'))
const stream2 = Readable.toWeb(fs.createReadStream('b.jpg'))
const results = await endpoint.uploadStreamGroup([stream1, stream2], ['image/jpeg', 'image/jpeg'])

// Remote URLs (the server fetches each)
const results = await endpoint.loadFromGroup(['https://example.com/a.jpg', 'https://example.com/b.jpg'])
```

图像顺序保存到端. 组合可能包含 **最多16个图像** (强制服务器侧). Pop的能力必须是多相能;单相能递出一个组返回出错.

### 取消任务

排队和进行中的工作可以从结果执行器中取消:

```typescript
const results = await endpoint.process({
    source: { url: 'https://demo-eyepop-videos.s3.amazonaws.com/test1_vlog.mp4' },
})

for await (const result of results) {
    console.log(result)
    if ((result.seconds ?? 0) >= 10) {
        results.cancel()
    }
}
```

## 终点选项

默认, `EyePop.workerEndpoint({ pop }).connect()` 需要时启动临时工,在连接时取消该工人的排队工作.

禁用工人启动 :

```typescript
const endpoint = await EyePop.workerEndpoint({ pop, autoStart: false }).connect()
```

保留待完成的工作 :

```typescript
const endpoint = await EyePop.workerEndpoint({ pop, stopJobs: false }).connect()
```

## 可视化

辅导员由 [@eyepop.ai/eyepop-render-2d (英语)](https://www.npmjs.com/package/@eyepop.ai/eyepop-render-2d)。 。 。 .

## 数据端点预览

`EyePop.dataEndpoint()` 为数据集管理和模型优化工作流程提供预览支持. 这个API是实验性的,可以改变.

## 可编译的流行

见 [可编译的流行](https://npmcn.com/package/%40eyepop.ai/eyepop/composable-pops.md) 用于客户端 Pop 构成.

## 常见问题

### @eyepop\.ai/eyepop 是什么？

EyePop\.ai推论 API 的官方Node\.js / Typescript 库

### 如何安装 @eyepop\.ai/eyepop？

在项目目录运行 npm install @eyepop\.ai/eyepop，或使用 pnpm add / yarn add / bun add。

### @eyepop\.ai/eyepop 支持 TypeScript 吗？

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

### @eyepop\.ai/eyepop 支持 ESM 还是 CommonJS？

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

### @eyepop\.ai/eyepop 可以商用吗？

@eyepop\.ai/eyepop 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @eyepop\.ai/eyepop 的下载量有多少？

根据 npm 官方下载统计，@eyepop\.ai/eyepop 在 2026/10/14 – 2026/11/12 这 30 天内被下载 3,610 次，日均约 120 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @eyepop\.ai/eyepop 还在维护吗？

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