# @bpinternal/gravity 中文文档

规范地址：https://npmcn.com/package/%40bpinternal/gravity/

版本：0\.2\.0
npm 元数据更新时间：2026-11-04T18:15:11.232Z
中文译文更新时间：2026-11-08T13:12:16.196Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bpinternal/gravity
原文对照：https://npmcn.com/package/%40bpinternal/gravity/?lang=original
项目主页：https://github.com/botpress/packages#readme
源码仓库：https://github.com/botpress/packages

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

- 包体积（解压后）：885 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=16\.0\.0
- 运行依赖：1 个
- 首次发布：2026-06-30T19:34:07.204Z
- 最新版本发布：2026-11-04T18:15:10.845Z
- 近 30 天下载量：10910（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

基于通用密度的集群(UMAP + HDBSCAN),从 Rust 编译为 Web Assembly.

## 安装

```sh
npm install @bpinternal/gravity
```

也可以使用：`pnpm add @bpinternal/gravity`、`yarn add @bpinternal/gravity`、`bun add @bpinternal/gravity`

## README

# @ bp 内部/ 重力

基于高维嵌入的通用密度集群 **无本地 依赖关系**。集群引擎用 Rust 写成,编译为 `wasm32-unknown-unknown`,然后用一个小的 TypeScript API 包起来——所以它随处可见 节点运行,没有系统库,安装时没有构建步骤.

管道将矢量减少到低维空间 **UMAP 地图**,然后将它们分组 与 **高频**。不会掉入任何密集区域的点会被作为噪音还原.

## 使用量

```ts
import { cluster } from '@bpinternal/gravity'

const result = cluster({
  ids: ['a', 'b', 'c', 'd'],
  embeddings: [
    [0.1, 0.2 /* ... */],
    [0.1, 0.3 /* ... */],
    [0.9, 0.8 /* ... */],
    [0.7, 0.1 /* ... */]
  ],
  dim: 1536
})

result.clusters // [{ itemIds, centroid, assignRadius }, ...]
result.noise // ids that weren't assigned to any cluster
result.labels // raw HDBSCAN label per input point, in input order (-1 = noise)
```

`embeddings[i]` 是用于 `ids[i]`,每个矢量必须准确 `dim` 组件.

### 选项

`cluster` 使用可选的第二个参数来覆盖 UMAP/HDBSCAN 参数. 任何未设置的字段都归为默认 .

```ts
cluster(dataset, {
  // UMAP (dimensionality reduction)
  initType: 'PCA', // 'PCA' | 'Random'           (default 'PCA')
  nNeighbors: 15, //   local neighborhood size    (default 15)
  nComponents: 5, //   reduced dimensions         (default 5)
  minDist: 0, //       packing tightness          (default 0)
  spread: 1, //        embedded scale             (default 1)
  nEpochs: 500, //     optimization epochs        (default 500)
  negativeSampleRate: 5, //                        (default 5)
  seed: 42, //         RNG seed (for determinism) (default 42)

  // HDBSCAN (density clustering)
  minClusterSize: 10, // min points per cluster   (default 10)
  minSamples: 1 //      core-distance neighbors   (default 1)
})
```

### 结果形状

| 外地 | 说明 |
| --- | --- |
| `clusters` | 所发现的集群. |
| `clusters[].itemIds` | 成员IDs,由与中心机器人相距上升的余弦所订购. |
| `clusters[].centroid` | 原始矢量空间中成员的平均值 . |
| `clusters[].assignRadius` | 余弦-相距半径( 已声明为 `[0.25, 0.35]`用于分配新分数. |
| `noise` | 没有指派给任何集群的编码 . |
| `labels` | 每个输入点的原始HDBSCAN标签,输入顺序. `-1` 这是噪音. |
| `umap_config` 编号 : `hdbscan_config` | 使用的参数 . |

运行是 **决定性**: 同一数据集,按相同的顺序,总是产生 相同的集群(UMAP以固定种子为种子).

## 如何运作

1.  **UMAP 地图** 将原始矢量(例如 1536-D) 投射到一个低维空间( 5- D) 使用余弦测量,保留局部结构.
2.  **高频** 在缩小的空间中找到密度集群(euclide 度量, EOM) 组合选择),将稀有点标记为噪声.
3.  中心点和任务半径在 **原文** 矢量空间是这样 下游代码可以通过同位素相似性来指定新的点.

## 发展

引擎就在这里 [`rssrc/`](https://npmcn.com/package/%40bpinternal/gravity/rssrc) 并暴露在WASM边界之外 `wasm-bindgen`。 。 。 . `wasm-pack` 编译到 `node` 财务报告和审定财务报表 `web` 目标, 原二进制是 base64-内入生成的胶水,以及 [`build.ts`](https://npmcn.com/package/%40bpinternal/gravity/build.ts) 捆绑 类型脚本包装入 [`src/`](https://npmcn.com/package/%40bpinternal/gravity/src) 绕着它去筑起。 这符合 在此重播中的其他 Rust 套件(`entities`, (中文(简体) ), `verel`) (中文(简体) ).

构建需要 Rust 工具链( 以 `wasm-pack`:

```bash
pnpm build        # wasm-pack (node + web) + esbuild bundles + type declarations
pnpm build:node   # just the Node target
pnpm build:web    # just the browser target
pnpm build:worker # just the Cloudflare Workers target
pnpm test         # run the Rust tests, then build the node target and run the wrapper tests
pnpm test:rust    # just the Rust unit tests (cargo)
pnpm test:unit    # just the TS wrapper tests (vitest)
pnpm check        # format + type check
```

建筑的发射 `dist/node` (共同公报), `dist/web` (ESM), `dist/worker` (ESM),以及 `dist/types`。节点和网络捆绑将原站作为基座64。 云花岗工人不能 从字节编译 Web Assembly, 所以 `dist/worker` 进口 `gravity_bg.wasm` 作为模块,其中 wrangler和 Cloudflare Vite 插件在构建时编译. 包裹 `workerd` 导出 条件选择它,所以 `import { cluster } from '@bpinternal/gravity'` 在一个工人中工作 没有设置.

## 免责声明

此软件包将在 `@bpinternal` 组织。 此所有软件包 组织意图用于: [瓶装](https://github.com/botpress/botpress) 内部的团队 并不适合我们的社区。 因为包裹是为我们准备的 自己的用例,它们的API可能不太稳定,接受断开的更改而无太多 缺乏以社区为重点的支持。 然而,这些 因为重要原因 开源. 因此,如果你想安装或叉子,这个软件包完全可以自由使用 做到这一点。 我们强烈建议你正确标记你的版本.

博讯工程组.

## 常见问题

### @bpinternal/gravity 是什么？

基于通用密度的集群\(UMAP \+ HDBSCAN\),从 Rust 编译为 Web Assembly\.

### 如何安装 @bpinternal/gravity？

在项目目录运行 npm install @bpinternal/gravity，或使用 pnpm add / yarn add / bun add。

### @bpinternal/gravity 支持 TypeScript 吗？

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

### @bpinternal/gravity 支持 ESM 还是 CommonJS？

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

### @bpinternal/gravity 需要什么版本的 Node\.js？

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

### @bpinternal/gravity 可以商用吗？

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

### @bpinternal/gravity 的下载量有多少？

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

### @bpinternal/gravity 还在维护吗？

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