# @dbx-tools/search 中文文档

规范地址：https://npmcn.com/package/%40dbx-tools/search/

版本：0\.9\.206
npm 元数据更新时间：2026-11-10T19:19:11.650Z
中文译文更新时间：2026-11-11T17:54:17.154Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40dbx-tools/search
原文对照：https://npmcn.com/package/%40dbx-tools/search/?lang=original
项目主页：https://github.com/reggie-db/dbx-tools#readme
源码仓库：https://github.com/reggie-db/dbx-tools

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

- 包体积（解压后）：536 kB，43 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：12 个
- 首次发布：2026-07-31T02:10:59.902Z
- 最新版本发布：2026-11-10T19:19:11.254Z
- 近 30 天下载量：7872（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：280（近 12 个月 280 个）

## 中文简介

AppKit AI 搜索的代理工具、联邦搜索、索引生命周期和Lakebase全文扩展

## 安装

```sh
npm install @dbx-tools/search
```

也可以使用：`pnpm add @dbx-tools/search`、`yarn add @dbx-tools/search`、`bun add @dbx-tools/search`

## README

# @ dbx 工具/ 搜索

添加代理工具, 联邦搜索, 索引生命周期帮助器, 或 a Lakebase支持的全文提供者给AppKit AI搜索. 使用本地应用程序 `aiSearch` 页:1 [数据砖 AI 搜索](https://docs.databricks.com/aws/en/ai-search/ai-search) 查询。 当代理服务器需要时添加此软件包 `search` 编号 : `universal_search`,应用程序需要创建、同步或种子索引,或 部署需要由 PostgreSQL 全文支持的相同的 AppKit 查询合同 搜索而不是矢量搜索.

## 快开始

围绕 AppKit AI 搜索索引添加扩展名 :

```ts
import { createApp, server } from "@databricks/appkit";
import { aiSearch } from "@databricks/appkit/beta";
import { search } from "@dbx-tools/search";

await createApp({
  plugins: [
    server(),
    aiSearch({ indexes: { docs: { indexName: "main.support.docs" } } }),
    search({ index: "main.support.docs" }),
  ],
});
```

延长部分补充如下:

-   矢量搜索向 AppKit 读取代表 `aiSearch`,用于处理身份 选择、缓存、重排、页码、路由验证和响应 解码.
-   `lakebaseAiSearch()` 执行相同的 `aiSearch` 化名、路线、, 客户端配置,以及 `SearchResponse` 与PostgreSQL的合同 `tsvector`。 。 。 .
-   Mastra 的代理工具 (`searchTool()` (通过) 扩展插件 `ToolProvider`: `search` 财务报告和审定财务报表 `universal_search` 读取,加上提供者-意识到的写作工具。 湖基地曝光事件 `add_documents`。 。 。 . 本地矢量搜索也可以曝光 `create_index` 财务报告和审定财务报表 `sync_index`。 。 。 .
-   下方的 AppKit 兼容查询路径 `/api/ai-search/:alias`扩展 路线 `/api/search` 覆盖通用搜索和可选生命周期 操作.
-   配置可以在您命名后推断出列、 页面大小、 模式和别名 默认索引或集 `DATABRICKS_VECTOR_SEARCH_INDEX`。 。 。 .
-   本地应用程序 `aiSearch` 默认使用服务本金。 设定 指数 `auth` 改为 `on-behalf-of-user` 当询问必须使用签名时 用户权限 。 每个Lakebase全文索引选择相同的两种模式 通过兄弟般的本土 `lakebase` 出行道池.
-   过滤器使用 AppKit 的 scalar/阵列形状 : `{ column: valueOrValues }`。 。 。 .
-   用于指数创建再利用的嵌入式模型分辨率 [@dbx-工具/型号](https://npmcn.com/package/%40dbx-tools/model)一个松散的名字 模糊的比对活的目录, 或自动选择最佳嵌入端点.
-   索引生命周期帮助者 : `createIndex` 编号 : `ensureIndex` (Delta同步从 a 源表,自管直接接入,带有维度或管理 包含文本列且不需要 Delta 表格或 仓库, `provision` (确保+种子在一个独能呼叫), `syncIndex`, (中文(简体) ), `deleteIndex`, (中文(简体) ), `listIndexes`,以及 `ensureEndpoint`每一个都推断出终点, 嵌入模式,主密钥,以及包默认的列.
-   提供启动索引 `ensureOnSetup`: 插件提供 使用本地 AppKit 的尾点 + 索引和种子文档 工作空间客户端,所以新部署是可搜索的,没有手动设置.
-   明确 **Lakebase 全文提供者**: 注册 `lakebaseAiSearch` 而不是本土 `aiSearch` 用于服务相同的别名、查询路线、过滤器, 和由 Postgres 生成的形状 `tsvector` 指数.

## 选择搜索提供者

普通矢量搜索不要使用此软件包, 而不是本地的 AppKit 查询。 登记册 `aiSearch` 从 `@databricks/appkit/beta`。 。 。 .

将这个软件包用于AppKit不运送的能力:代理工具供应商, 联合粉丝出厂、索引寿命周期和播种、可重复使用的结果组件,或 lakebase全文执行AppKit AI搜索合同.

注册本地 `aiSearch` 用于数据砖矢量搜索。 登记册 `lakebaseAiSearch` 使用相同的 AppKit 查询进行 PostgreSQL 全文搜索 合同。 他们都使用 `aiSearch` 插件名称, 所以应用程序必须 选择一个。 添加 `search()` 代理商需要工具时,除选定供应商外, 联邦读物,或生命周期路线.

## 添加搜索到 Mastra 代理

```ts
import { createApp, server } from "@databricks/appkit";
import { aiSearch } from "@databricks/appkit/beta";
import { search } from "@dbx-tools/search";
import { agents, mastra } from "@dbx-tools/appkit-mastra";

const support = agents.createAgent({
  instructions: "Answer from the docs; use `search` to find them.",
  async tools(plugins) {
    return { ...(await plugins.search.toolkit()) };
  },
});

await createApp({
  plugins: [
    server(),
    aiSearch({
      indexes: {
        docs: {
          indexName: "main.support.docs",
          columns: ["id", "title", "url", "body"],
        },
      },
    }),
    search({
      index: "main.support.docs",
      indexes: [{ name: "main.support.docs", alias: "docs" }],
    }),
    mastra({ agents: support }),
  ],
});
```

每个 `search()` 插件保留其解析后的配置、客户端和提供者后端 分开. 如上所示,App-Integration剂应消耗其原生工具包 保持电话连接在那个插件上 。 独立的马斯特拉工厂接受 明确运行时间, 或配置加提供者 :

```ts
import { runtime, tool } from "@dbx-tools/search";

const searchRuntime = runtime.createSearchRuntime({
  config: { index: "main.support.docs" },
  readBackend,
});
const search = tool.searchTool({ runtime: searchRuntime });
```

使用 Lakebase 全文搜索而不更改 AppKit UI 钩:

```ts
import { lakebase } from "@databricks/appkit";
import { lakebaseAiSearch } from "@dbx-tools/search";

createApp({
  plugins: [
    lakebase(),
    lakebaseAiSearch({
      indexes: {
        docs: {
          indexName: "docs",
          columns: ["id", "title", "body"],
          queryType: "full_text",
        },
      },
    }),
  ],
});
```

## 管理索引

`SearchClient` 是生命周期客户端。 查询执行需要注册 AppKit相容供应商. 一个三角洲 同步索引计算从源 Delta 表格嵌入并保持同步 。 这个 嵌入模型、端点、主键(`id`)和文本栏 (单位:千美元)`text`编号 :`content`编号 :`body`)在省略时全部被推断出.

```ts
const client = createSearchClient();

// Ensure the Vector Search endpoint exists (creates a STANDARD one if not).
await client.ensureEndpoint("my-vs-endpoint", { wait: true });

// Delta Sync index from a Delta table (embeddings computed by Databricks).
await client.ensureIndex("main.support.docs", {
  endpoint: "my-vs-endpoint",
  sourceTable: "main.support.docs_source",
  // embeddingModel / primaryKey / embeddingSourceColumn inferred when omitted
});

// Trigger a sync, then later delete.
await client.syncIndex("main.support.docs");
await client.deleteIndex("main.support.docs");

// Managed direct-access index: Databricks embeds a
// text column on write AND query, so no Delta table, no warehouse, no vectors.
await client.createIndex("main.support.docs", {
  endpoint: "my-vs-endpoint",
  // managed by default when no embeddingDimension is given
});
await client
  .index("main.support.docs")
  .addDocuments([{ id: "1", text: "AI Search finds the most relevant documents for a query." }]);

// Self-managed direct-access index you write vectors to yourself.
await client.createIndex("main.support.vectors", { embeddingDimension: 1024 });
await client.index("main.support.vectors").addDocuments([{ id: "1", embedding: [/* … */] }]);

// One call to make an index real AND seeded (idempotent - safe every boot).
await client.provision("main.support.docs", {
  endpoint: "my-vs-endpoint",
  seed: [{ id: "1", text: "Databricks AI Search overview", url: "https://…" }],
});
```

这个 `SearchIndex` 处理镜像 : `index.ensure(opts)`, (中文(简体) ), `index.sync()`, (中文(简体) ), `index.delete()`, (中文(简体) ), `index.info()`。 。 。 .

当插件的写入表面被启用( W)`search({ allowWrite: true })` 或者说 `SEARCH_WRITE=true`),特工获得与工具相同的生命周期: `create_index` 提供附有所有推断的索引(通过 `sourceTable` 联 合 国 常见的 Delta 同步大小写,或 `embeddingDimension` 以直接获得的指数为准, 财务报告和审定财务报表 `sync_index` 从源表格刷新 Delta 同步索引.

`allowWrite` 揭露这些工具,但不批准. AppKit 标记它们 与 `effect: "write"` 作为请求用户运行。 马斯特拉适配器 不暂停常规的写效果。 如果写作需要人类批准, 为 Mastra 工具注册 `requireApproval: true` 呼唤 `SearchClient` 运行后恢复而非直接曝光写入工具包.

### 提供靴子索引

`ensureOnSetup` 提供应用程序启动时的索引, 使用本地 AppKit 工作空间客户端. 它在缺失和 种子文档仅当索引为空时。 本作在背景中展开, 因此,一个缓慢的第一次端点构建不会阻挡服务器. 默认是管理下的直通索引,所以种子行是平坦的 对象和按文本搜索的工作没有三角洲表或仓库.

```ts
search({
  index: "main.support.docs",
  endpoint: "my-vs-endpoint",
  ensureOnSetup: {
    embeddingModel: "databricks-gte-large-en", // optional; best embedding endpoint otherwise
    documents: [
      { id: "1", title: "Overview", text: "AI Search finds relevant docs.", url: "https://…" },
      { id: "2", title: "Indexes", text: "Delta Sync vs. direct access." },
    ],
    // schema inferred from the first row; primaryKey/textColumn default to id/text
  },
});
```

同上:后面的靴子见已存在的终点、索引和行 没什么 点 `ensureOnSetup.sourceTable` 在三角洲表格中提供三角洲 同步索引而不是管理下的直通索引 .

### Lakebase 全文提供者

`lakebaseAiSearch()` 是一个 AppKit `aiSearch` 由 Postgres 支持的提供者 全文索引。 它规定每个别名一个表格(生成) `tsvector` ,并使用 前缀 `to_tsquery` + 键 `ts_rank`游泳池来自本地 `lakebase` 插件的路由池,所以数据库认证没有被重新执行. HTTP 密码 调用者无法扩大已配置的投影列 . `columns` 覆盖保留 仅供信任的方案使用 `query()` 打电话 设置索引 `auth` 改为 `on-behalf-of-user` 为OBO查询/写路由,或将其留在 `service-principal`。 。 。 .

查询是从搜索框中汇编的,而不是交给 `websearch_to_tsquery`,这在两种方式中对于类型前方来说太字形了:

-   **标点:** 邮资指数 `sample-store-intelligence` 作为 复合的 lexeme 加上其部件,但汇编一个连字符查询到 单靠复合物 结果, `store-intelligence` 不匹配时 `store intelligence` 和一切一样 查询是按点划分的, 因此,两种拼法(和 `.` 编号 : `_` 在表格引用中)行为相同.
-   **前缀 :** 每个术语都是前缀,所以 `intel` 达到 `intelligence` 财务报告和审定财务报表 `store intel` 发现 `sample-store-intelligence`。 。 。 .

所有条件必须相符。 没有的时候,搜索会放松而不是返回 空框: 任何单个名词都算数, 加上一个接下字符串 非前缀的片段( x)`telligence`) (中文(简体) ). 无法使用子字符串 gIN指数,所以它只在指数化的通关之后运行.

提供者返回 AppKit 的 `SearchResponse` 并挂载同样的 `/api/ai-search/:alias` 查询表面。 AppKit 用户界面 `useAiSearchQuery` 财务报告和审定财务报表 `@dbx-tools/ui/search` 没有后端特定客户端的工作 :

```ts
import { createApp, lakebase } from "@databricks/appkit";
import { lakebaseAiSearch } from "@dbx-tools/search";

createApp({
  plugins: [
    lakebase(),
    lakebaseAiSearch({
      indexes: {
        docs: {
          indexName: "docs",
          queryType: "full_text",
          columns: ["id", "title", "text"],
          documents: [{ id: "1", title: "Overview", text: "Search over Postgres full-text." }],
        },
      },
    }),
  ],
});
```

在本地注册 `aiSearch` 用于矢量搜索或 `lakebaseAiSearch` 页:1 邮编全文. 两者都使用已注册的插件名称 `aiSearch`,所以他们是 不得一起登记.

## 配置

所有字段都是可选的. 优先是插件配置,然后是环境,然后是环境 默认.

| 配置 | 环境 | 默认 | 目的 |
| --- | --- | --- | --- |
| `index` | `SEARCH_INDEX`, (中文(简体) ), `DATABRICKS_VECTOR_SEARCH_INDEX` | 无 | 默认索引(名或别名). |
| `indexes` | 无 | `[index]` | 以别名,通用搜索,和UI而出名的索引. |
| `endpoint` | `SEARCH_ENDPOINT` | 无 | 矢量搜索端点(只需要创建索引). |
| `columns` | `SEARCH_COLUMNS` | 索引栏 | 每次命中默认列. |
| `pageSize` | `SEARCH_PAGE_SIZE` | `10` | 每次搜索的默认点击数 . |
| `mode` | `SEARCH_MODE` | `hybrid` | `hybrid` 编号 : `vector` 编号 : `keyword`。 。 。 . |
| `embeddingModel` | `SEARCH_EMBEDDING_MODEL` | 最佳嵌入端点 | 嵌入索引创建的端点 . |
| `timeoutMs` | `SEARCH_TIMEOUT_MS` | `30000` | 呼叫暂停. |
| `allowWrite` | `SEARCH_WRITE` | `false` | 启用提供者支持的写工具和路由 . |
| `ensureOnSetup` | 无 | 无 | 在靴子上提供和播种本地矢量搜索索引. |

## 模块

-   `client` - 说吧 `SearchClient`, (中文(简体) ), `SearchIndex`和矢量搜索生命周期 (单位:千美元)`createIndex` 编号 : `ensureIndex` 编号 : `syncIndex` 编号 : `deleteIndex` 编号 : `listIndexes` 编号 : `ensureEndpoint`),加上供应商支持的联邦阅读.
-   `plugin` - 说吧 `SearchPlugin` 编辑 `search()` 工厂`ToolProvider`, (中文(简体) ), 路线, `clientConfig`, (中文(简体) ), `exports`) (中文(简体) ).
-   `tool` - 那个 `searchTool()`, (中文(简体) ), `universalSearchTool()`, (中文(简体) ), `addDocumentsTool()`, (中文(简体) ), `createIndexTool()`,以及 `syncIndexTool()` 马斯特拉工厂.
-   `index-tools` - 说吧 `toCreateIndexOptions`,来自 `create_index` 有线请求进入 `SearchClient.createIndex` 选项(由 mastra 工具和插件路由.
-   `config` - 说吧 `resolveSearchConfig`, (中文(简体) ), `resolveIndexName`, (中文(简体) ), `SEARCH_CONFIG_SCHEMA`, (中文(简体) ), 内嵌的常数 `SearchPluginConfig` 编号 : `ResolvedSearchConfig` 类型.
-   `native` - AppKit兼容软件的适配器 `aiSearch` 提供给 扩展工具和通用搜索客户端.
-   `lakebase-plugin` - 说吧 `lakebaseAiSearch`, AppKit 兼容 PostgreSQL 软件 全文提供者.
-   `lakebase` - 说吧 `LakebaseSearchBackend`,供应商的 `tsvector` 运行时间.
-   `query` - 说吧 `toDocumentArray`,通过写路由和工具共享.
-   `runtime` - 说吧 `createSearchRuntime` 编号 : `setSearchReadBackend` 为孤立的客户.
-   `schema` - 工具说明和再出口的请求计划.

浏览器安全计划 [@ dbx- 工具/ 共享搜索](https://npmcn.com/package/shared/search)。反应搜索框 住在这里 [@dbx-tools/ui/ search (英语)](https://npmcn.com/package/ui/appkit). 示范决议再利用 [@dbx-工具/型号](https://npmcn.com/package/%40dbx-tools/model)。 。 。 .

## 常见问题

### @dbx-tools/search 是什么？

AppKit AI 搜索的代理工具、联邦搜索、索引生命周期和Lakebase全文扩展

### 如何安装 @dbx-tools/search？

在项目目录运行 npm install @dbx-tools/search，或使用 pnpm add / yarn add / bun add。

### @dbx-tools/search 支持 TypeScript 吗？

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

### @dbx-tools/search 支持 ESM 还是 CommonJS？

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

### @dbx-tools/search 可以商用吗？

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

### @dbx-tools/search 的下载量有多少？

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

### @dbx-tools/search 还在维护吗？

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