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

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

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

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

设计与模拟等价细节 : 设计

快速启动

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 密码

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

选项

源配置

// 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源不支持(取而代之的是使用本地文件夹路径).

弹簧策略

弹入选项

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

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

获取选项

获取结果

同步

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

// 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:// 在沙盒/生产中,同步状态真正反映可查询性.

元数据过滤

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

// 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,则看到 获取的内容是不可信的 在代理文件.

处理错误

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;
}

部署行为

cdk deploy 自动触发文档摄取(fire- and-forget). 部署完成后,摄入会同步运行. 检查 AWS 控制台以监视摄取进度, 或调用 isSynced() 编号 : waitUntilSynced() 从代码到门查询摄入完成情况.

缩放成本( 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。 。 。 .

另见

• 亚马逊贝德罗克知识库