# @aws-blocks/bb-knowledge-base 中文文档

规范地址：https://npmcn.com/package/%40aws-blocks/bb-knowledge-base/

版本：0\.3\.0
npm 元数据更新时间：2026-11-02T10:26:03.516Z
中文译文更新时间：2026-11-07T13:40:55.880Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aws-blocks/bb-knowledge-base
原文对照：https://npmcn.com/package/%40aws-blocks/bb-knowledge-base/?lang=original
项目主页：https://github.com/aws-devtools-labs/aws-blocks/tree/main/packages/bb-knowledge-base#readme
源码仓库：https://github.com/aws-devtools-labs/aws-blocks

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

- 包体积（解压后）：510 kB，60 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：constructs ^10\.6\.0，aws-cdk-lib ^2\.257\.0
- 首次发布：2026-06-15T23:39:41.346Z
- 最新版本发布：2026-11-02T10:26:03.140Z
- 近 30 天下载量：63114（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

语义文档检索由亚马逊·贝德罗克知识库支持.

## 安装

```sh
npm install @aws-blocks/bb-knowledge-base
```

也可以使用：`pnpm add @aws-blocks/bb-knowledge-base`、`yarn add @aws-blocks/bb-knowledge-base`、`bun add @aws-blocks/bb-knowledge-base`

## README

# @aws-blocks/bb-knowledge-base (英语)

语义文档检索由亚马逊·贝德罗克知识库支持.

**何时使用 :** 搜索你自己的文档——FAQs,产品指南,支持文章,内部维基. 用自然语言指向文件夹和查询.

**不使用时 :** 如果需要结构化的密钥值查询,请使用 `KVStore`。如果需要关系查询,请使用 `Database`。如果仅需要全文关键字搜索(没有语义理解),请使用 `DistributedTable`。 。 。 .

> 设计与模拟等价细节 : [设计](https://npmcn.com/package/%40aws-blocks/bb-knowledge-base/DESIGN.md)

## 快速启动

```typescript
import { Scope, ApiNamespace } from '@aws-blocks/core';
import { KnowledgeBase } from '@aws-blocks/bb-knowledge-base';

const scope = new Scope('my-app');

const kb = new KnowledgeBase(scope, 'docs', {
  source: './knowledge',
  description: 'Product documentation',
});

export const api = new ApiNamespace(scope, 'api', (context) => ({
  async search(query: string) {
    const results = await kb.retrieve(query, { maxResults: 5 });
    return { results };
  },
}));
```

## API 密码

```typescript
const kb = new KnowledgeBase(scope, id, options)
```

| 方法 | 回返 | 说明 |
| --- | --- | --- |
| `retrieve(query, options?)` | `Promise<RetrieveResult[]>` | 搜索相关的文档块 。 返回结果按相关分数排序. |
| `isSynced()` | `Promise<boolean>` | KB 是否与您的最新数据同步 . `true` 一旦最新的摄入工作是 `COMPLETE` (或无BB管理的数据源可追踪). 报告数据 _新鲜度_,不可用—— `retrieve()` 总是可以调用,并在重新摄入飞行时为前一个快照服务。 掷出 `IngestionFailed` 如果最近的工作失败. |
| `waitUntilSynced(options?)` | `Promise<void>` | 票价 `isSynced()` 直至 KB 与您的最新数据同步或超时。 掷出 `Timeout` 如果无法及时同步。 接受可选选项 `AbortSignal` 取消等待. |

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `source` | `string` | (必须) | 文档来源 — 本地文件夹路径或 `s3://` URI指向一桶或文件夹. |
| `chunking` | `ChunkingConfig` | `{ strategy: 'semantic' }` | 文件如何分割成块 . |
| `embeddingDimensions` | `256 | 512 | 1024` | `1024` | 嵌入模型维度. |
| `description` | `string` | —— 说 | 知识库的可人阅读描述. |
| `removalPolicy` | `'destroy' | 'retain'` | 堆栈 `defaults` | BB 创建数据桶的 CDK 删除行为( 已导入) `s3://` URI来源不受影响. 省略时,请跟随整个堆栈 `defaults` (单位:千美元)`production` 扣留, `sandbox` ~ 战败. 过 `'destroy'` 为这个 KB 将桶倒下 `autoDeleteObjects`。 。 。 . |
| `logger` | `ChildLogger` | —— 说 | 内部操作的可选日志。 省略时,会在错误级别创建默认 Logger . |

### 源配置

```typescript
// Local folder — synced to S3 on deploy
new KnowledgeBase(scope, 'docs', { source: './knowledge' });

// Existing S3 bucket (with optional prefix)
new KnowledgeBase(scope, 'docs', { source: 's3://my-bucket' });
new KnowledgeBase(scope, 'docs', { source: 's3://my-bucket/docs/prefix/' });
```

**S3 URI 来源 :** 当使用时 `s3://` URI, CDK 构造导入了已存在的桶, 而不是创建一个新的桶 。 一个可选的路径前缀收缩对象 Bedrock 吞噬。 没有 `BucketDeployment` 已创建 —— 您的文档必须已经在桶中 。 在本地开发中,S3 URI源不支持(取而代之的是使用本地文件夹路径).

### 弹簧策略

| 战略 | 说明 |
| --- | --- |
| `'semantic'` | (default) 使用断点检测在自然主题边界进行分解. |
| `'fixed'` | 可配置的固定大小块 `chunkSize` 财务报告和审定财务报表 `chunkOverlap`。 。 。 . |
| `'hierarchical'` | 双层块(父母1500个令牌,孩子300个令牌). |
| `'none'` | 没有块块——每个文件都是单个块. |

### 弹入选项

`chunking` 接受一个 `ChunkingConfig`选项仅适用于相关战略;其他选项则被忽视.

| 选项 | 类型 | 默认 | 适用于 | 说明 |
| --- | --- | --- | --- | --- |
| `strategy` | `'semantic' | 'fixed' | 'hierarchical' | 'none'` | `'semantic'` | 全部 | 春京战略. |
| `chunkSize` | `number` | `300` | `'fixed'` | 每块最大标记值 . |
| `chunkOverlap` | `number` | `20` | `'fixed'` | 相接块之间的重叠百分比(0-100). |
| `breakpointPercentile` | `number` | `95` | `'semantic'` | 断点百分数用于主题边界检测(0-100). |

```typescript
chunking: { strategy: 'fixed', chunkSize: 500, chunkOverlap: 10 }
```

### 获取选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `maxResults` | `number` | `10` | 最大结果返回 。 范围:1-100. |
| `filter` | `MetadataFilter` | —— 说 | 元数据过滤器与所有键值对的和语义. |

### 获取结果

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `text` | `string` | 春克文本内容. |
| `score` | `number` | 相关性得分为0.0-1.0. |
| `source` | `string` | 源文档路径或 URL. |
| `metadata` | `Record<string, string>` | 文件元数据。 包括自动人口 `folder` 从子文件夹. |

### 同步

贝德洛克摄入在部署后同步运行,所以在部署后立即进行 `cdk deploy` 知识库尚未与您的最新数据同步 `retrieve()` 返回一个空数组,即使是对以后匹配的查询。 (一旦至少一项摄入工作完成, `retrieve()` 总是提供最新的同步快照, 即使后来的再摄入正在飞行中。 ) 使用 `isSynced()` 编号 : `waitUntilSynced()` 到摄入完成时的门 :

```typescript
// Block until the KB is synced with your latest data (e.g. right after deploy), then query
await kb.waitUntilSynced({ timeoutMs: 600_000 });
const results = await kb.retrieve('getting started');

// Or check without blocking
if (await kb.isSynced()) {
  const results = await kb.retrieve('getting started');
}

// Cancel the wait with an AbortSignal (e.g. an overall request deadline)
await kb.waitUntilSynced({ signal: AbortSignal.timeout(120_000) });
```

`waitUntilSynced(options?)` 接受 `timeoutMs` (默认) `300_000`, (中文(简体) ), `pollIntervalMs` (默认) `5_000`(b) 被夹住至最少一米, `maxConsecutiveTransientErrors` (默认) `3`最低限度 `0`),可选 `signal` (单位:千美元)`AbortSignal`) (中文(简体) ). 民意调查间隔带少量随机焦虑(±20%) _介于_ 民意调查 永远不要把睡眠推过 `timeoutMs`。 。 。 .

`maxConsecutiveTransientErrors` 是编号 _连续_ 暂时控制飞机的错误在放弃之前是容忍的;计数器在任何干净的民意调查中都得到了恢复。 有两个条件被视作是短暂的和漫游的: 节流/短暂的网络故障, **财务报告和审定财务报表** (单位:千美元) _未可见_ 知识库——在部署后窗口中,控制平面可以短暂返回 `ResourceNotFoundException` (新创建的 KB 或数据源尚未传播) `waitUntilSynced()` 吸收而不是放弃 终端错误总是立即短路, 不论限制为何: a `FAILED` 摄取工作,a _缺少 KB 配置_ 错误( `KB_ID` env var是未被设定的——区别于瞬间不相见的情况. 何时 `signal` 提供等待,即时取消等待(在每次民意测验前和在民意测验间延误期间检查),以信号的中止理由拒绝等待(默认为a) `DOMException` 名称 `'AbortError'`) (中文(简体) ).

本地文件夹和进口 `s3://` 源注册一个BB管理的数据源,所以同步状态反映了数据源在两种情况下的摄取工作. (此同步 API 之前的部署没有输入数据源 id , 因此 `isSynced()` 返回时 `true` 立即——没有什么可追踪的。 ) 这个预选部署是 **仅限** 情况 `isSynced()` 返回时 `true` 未经咨询实际摄取工作——重新调配注射者 `DATA_SOURCE_ID` 并恢复真实的跟踪,因此新部署的KB总是反映真实的工作状态(不要错误地将"无物可追踪"的捷径用于"摄入确认的完整"时的活塞). 在本地开发中,模型总是同步。 注意当地 `isSynced()` 联 合 国 `true` 已经 **没有** 隐含 `retrieve()` 工作于一个 `s3://` 源 - 模拟拒绝 `s3://` 与 `InvalidSourceConfigException` (生产合同的反向),因此验证 `s3://` 在沙盒/生产中,同步状态真正反映可查询性.

## 元数据过滤

通过文档元数据过滤结果. 所有条件使用和语义:

```typescript
// Only return chunks from the 'faq' folder
const results = await kb.retrieve('how do I reset my password', {
  filter: { folder: { equals: 'faq' } },
});

// Multiple filters (AND)
const results = await kb.retrieve('pricing', {
  filter: {
    folder: { equals: 'products' },
    category: { equals: 'enterprise' },
  },
});
```

子文件夹路径自动填充 `folder` 元数据密钥。 例如,一个文件在 `./knowledge/faq/billing.md` 获得 `metadata.folder = 'faq'`。 。 。 .

## 信任边界

知识库是一个指数,不是每个用户或租户一个指数 `retrieve()` 返回任意匹配。 有两个后果:

-   **一个过滤器是一个查询范围,而不是访问控制.** 如果您将多个用户或租户的文档保存在一个知识库中, 请将服务器代码中的过滤器从认证的呼叫器中设置( 例如) `filter: { tenant: { equals: user.tenantId } }`) (中文(简体) ). 绝不取自请求体或代理工具的输入,或呼叫者可以通过修改来读取其他租户的文件.
-   **索引文本不可信 .** 如果一个来源能收到内容,你不会自己写,例如 `s3://` 来源为 a `FileBucket` 您的用户上传到, 该内容到达任何检索它的人。 当结果送到一个剂时,它们可以携带指示,试图使其滥用其工具(间接即时注射). 标记调用代理工具 `retrieve()` 与 `untrustedOutput: true`,则看到 [获取的内容是不可信的](https://npmcn.com/package/%40aws-blocks/bb-agent/README.md#retrieved-content-is-untrusted) 在代理文件.

## 处理错误

```typescript
import { isBlocksError } from '@aws-blocks/core';
import { KnowledgeBaseErrors } from '@aws-blocks/bb-knowledge-base';

try {
  const results = await kb.retrieve('query');
} catch (e: unknown) {
  if (isBlocksError(e, KnowledgeBaseErrors.NotReady)) {
    // KB not yet deployed or ingested
  }
  if (isBlocksError(e, KnowledgeBaseErrors.ValidationError)) {
    // Empty query
  }
  throw e;
}
```

| 错误常数 | 名称 | 何时 |
| --- | --- | --- |
| `KnowledgeBaseErrors.RetrievalFailed` | `RetrievalFailedException` | Bedrock 检索呼叫失败 |
| `KnowledgeBaseErrors.NotReady` | `KnowledgeBaseNotReadyException` | KB 未部署或未嵌入 vars 缺失 |
| `KnowledgeBaseErrors.IngestionFailed` | `IngestionFailedException` | 最新摄入任务失败( 消息包括 `failureReasons`)——被抛出 `isSynced()` 编号 : `waitUntilSynced()` |
| `KnowledgeBaseErrors.Timeout` | `KnowledgeBaseTimeoutException` | `waitUntilSynced()` 超过摄入完成前的超时 |
| `KnowledgeBaseErrors.InvalidSource` | `InvalidSourceConfigException` | 未找到或无效的源文件夹配置 |
| `KnowledgeBaseErrors.InvalidFilter` | `InvalidFilterException` | Bedrock 查询中无效的过滤键 |
| `KnowledgeBaseErrors.ValidationError` | `KnowledgeBaseValidationError` | 空或无效查询 |
| `KnowledgeBaseErrors.BrowserNotSupported` | `BrowserNotSupportedException` | 在一个浏览器上下文中使用 —— KnowledgeBase 只为服务器侧 |

## 部署行为

`cdk deploy` 自动触发文档摄取(fire- and-forget). 部署完成后,摄入会同步运行. 检查 AWS 控制台以监视摄取进度, 或调用 [`isSynced()` 编号 : `waitUntilSynced()`](https://npmcn.com/package/%40aws-blocks/bb-knowledge-base/#readme-sync) 从代码到门查询摄入完成情况.

## 缩放成本( AWS)

-   **嵌入模型 :** 亚马逊泰坦文字嵌入 V2
-   **向量存储 :** S3 矢量( 无服务器, 无给养)
-   **嵌入成本 :** ~ 0.00002美元/千个令牌(摄入)
-   **检索费用:** ~ $0.00002 每1,000个令牌( 以克来嵌入) + S3 矢量查询成本
-   **存储 :** S3 源文档的标准定价 + S3 嵌入矢量
-   **最大文档大小 :** 每个文件 50 MB
-   **支持的格式 :** .md,.txt,.html,.htm,.csv,.json(附加在AWS上解析的二进制格式:.pdf,.docx,.docx,.xls,.xlsx)

## 地方发展

在本地 dev 模式下, KnowledgeBase 从源文件夹读取文档, 按照配置的块分割成块 `chunking` 策略,并使用TF-IDF进行关联评分. 结果被缓存到 `.bb-data/{fullId}/chunks.json` 对于快速重启;缓存在源文件夹的内容和块配置上按键,当文件被添加、编辑或删除,或块设置被更改时自动重建.

**均等注释 :**

-   Scoring使用TF-IDF(以键字为主)而不是真正的嵌入. 积分在模拟器内部是相对的,不会完全匹配出出出品"贝德洛克"的分数.
-   TF-IDF的表示器为Unicode-aware:口音被正常化(所以) `resume` 匹配 `résumé`)和CJK文本通过字符bigrams匹配.
-   春金在本地大致为: `'fixed'` 使用字数窗口(`chunkSize`编号 :`chunkOverlap`, (中文(简体) ), `'none'` 保持每个文档的完整 `'semantic'` (和 `'hierarchical'`)在段落界限上分出.
-   `chunkOverlap` 是一个 **百分比** 联 合 国 `chunkSize` 两种环境中的模拟重叠: `chunkSize × chunkOverlap / 100` 和CDK图层将其映射到贝德洛克的 `overlapPercentage` (1-99) (中文(简体) ). 该值在本地 dev 和生产之间直接可转移.
-   API合同(方法签名,出错类型,结果形状)与AWS完全相同.
-   `maxResults` 一样的工作。 元数据过滤使用相同的 `equals`/AND语义,有一个不对称:在生产中,未知或无效的过滤键是 _常规_ 被 Bedrock 拒绝的服务器侧( 表面为 `InvalidFilterException` 当服务标记过滤器时),而本地模拟无声匹配,返回空结果集.
-   `source` 必须是工程目录内部的相对路径——逃离工程的绝对路径(通过 `..`) 被拒绝 `InvalidSourceConfigException`. S3 URI源在本地开发中没有支持——使用本地文件夹路径.

擦去缓存数据 `rm -rf .bb-data`。 。 。 .

## 另见

-   [亚马逊贝德罗克知识库](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html)

## 常见问题

### @aws-blocks/bb-knowledge-base 是什么？

语义文档检索由亚马逊·贝德罗克知识库支持\.

### 如何安装 @aws-blocks/bb-knowledge-base？

在项目目录运行 npm install @aws-blocks/bb-knowledge-base，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：constructs（^10\.6\.0）、aws-cdk-lib（^2\.257\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-blocks/bb-knowledge-base 支持 TypeScript 吗？

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

### @aws-blocks/bb-knowledge-base 支持 ESM 还是 CommonJS？

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

### @aws-blocks/bb-knowledge-base 可以商用吗？

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

### @aws-blocks/bb-knowledge-base 的下载量有多少？

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

### @aws-blocks/bb-knowledge-base 还在维护吗？

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