# @agentskit/rag 中文文档

规范地址：https://npmcn.com/package/%40agentskit/rag/

版本：0\.7\.1
npm 元数据更新时间：2026-10-24T15:08:49.458Z
中文译文更新时间：2026-11-06T03:49:42.033Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40agentskit/rag
原文对照：https://npmcn.com/package/%40agentskit/rag/?lang=original
项目主页：https://www.agentskit.io/docs/reference/packages/rag
源码仓库：https://github.com/AgentsKit-io/agentskit

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

- 包体积（解压后）：763 kB，26 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19
- 运行依赖：3 个
- peer 依赖：@aws-sdk/client-s3 ^3\.0\.0
- 首次发布：2026-04-06T14:27:11.572Z
- 最新版本发布：2026-10-24T15:08:48.973Z
- 近 30 天下载量：5332（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：43（近 12 个月 43 个）

## 中文简介

为"特工Kit"提供插件和游戏回取功能.

## 安装

```sh
npm install @agentskit/rag
```

也可以使用：`pnpm add @agentskit/rag`、`yarn add @agentskit/rag`、`bun add @agentskit/rag`

## README

# @ agentskit/ 擦伤

![AgentsKit](https://raw.githubusercontent.com/AgentsKit-io/agentskit/main/apps/docs-next/public/brand/logo-wordmark.svg)

插件和游戏取回加载生成:块化文档,嵌入到其中,并在查询时检索到正确的上下文.

[![npm version](https://img.shields.io/npm/v/@agentskit/rag?color=blue)](https://www.npmjs.com/package/@agentskit/rag) [![npm downloads](https://img.shields.io/npm/dm/@agentskit/rag)](https://www.npmjs.com/package/@agentskit/rag) [![bundle size](https://img.shields.io/bundlejs/size/@agentskit/rag?label=bundle)](https://bundlejs.com/?q=@agentskit/rag) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/LICENSE) [![stability](https://img.shields.io/badge/stability-beta-yellow)](https://npmcn.com/package/docs/STABILITY.md) [![GitHub stars](https://img.shields.io/github/stars/AgentsKit-io/agentskit?style=social)](https://github.com/AgentsKit-io/agentskit)

**标记 :** `ai` • 妇女 `agents` • 妇女 `llm` • 妇女 `agentskit` • 妇女 `rag` • 妇女 `retrieval` • 妇女 `vector-search` • 妇女 `embeddings` • 妇女 `ai-agents` • 妇女 `semantic-search` • 妇女 `knowledge-base`

## 已核实的证据

-   软件包元数据和测试在 `packages/rag/`。 。 。 .
-   软件包指南 : [https://www.agentskit.io/docs/参考文献/packages/rag](https://www.agentskit.io/docs/reference/packages/rag)
-   稳定地图: [文件/服务.md](https://npmcn.com/package/docs/STABILITY.md)

## 如何适应生态系统

@ agentskit/ rag 是取回层: 装入文档, 块入文档, 嵌入文档, 重新排序结果, 并将精确的上下文反馈给代理 .

-   **探员Kit**:与本回购中的其他包一起作曲,从可互换的小零件来构建代理.
-   **书记官处**: 查找已使用此图层的即时代理和模板 [登记. agentskit.io](https://registry.agentskit.io/)。 。 。 .
-   **游戏本**: 学习本层背后的生产模式 [游戏本. agentskit.io](https://playbook.agentskit.io/)。 。 。 .

文档 : [软件包指南](https://www.agentskit.io/docs/reference/packages/rag) • 妇女 [代理交接](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt)

## 为什么是布

-   **你的数据 你的经纪人** 不需要微调;用自然语言吸收纯文本和查询
-   **可编译堆栈** - 使用任意 `EmbedFn` 和任何 `VectorMemory` 从 `@agentskit/adapters` 财务报告和审定财务报表 `@agentskit/memory`; 在不触碰RAG逻辑的情况下互换任意一层
-   **检索准备** —— 说 `createRAG()` 返回 a `Retriever` 交给你 `@agentskit/runtime` 或者说 `useChat` 自动注入上下文
-   **没有博士学位的Tune块** —— 说 `chunkSize`, (中文(简体) ), `chunkOverlap`,或习惯 `split` 函数——涵盖95%使用案例的3个键

## 安装

```bash
npm install @agentskit/rag @agentskit/memory @agentskit/adapters
```

文件支持的示例也需要可选 `vectra` 鼠标。 添加 `vectra` 安装命令 `fileVectorMemory`; 运行时间 融合的例子,特别是需求 `@agentskit/runtime`。 。 。 .

## 快速实例

```ts
import { createRAG } from '@agentskit/rag'
import { openaiEmbedder } from '@agentskit/adapters'
import { fileVectorMemory } from '@agentskit/memory'

const rag = createRAG({
  embed: openaiEmbedder({ apiKey: process.env.OPENAI_API_KEY! }),
  store: fileVectorMemory({ path: './vectors' }),
})

await rag.ingest([
  { id: 'doc-1', content: 'AgentsKit is a JavaScript agent toolkit...' },
])

const docs = await rag.search('How does AgentsKit work?', { topK: 5 })
console.log(docs)
```

## 有运行时间( 返回)

通过RAG实例为 `retriever` 因此,运行时间将检索到任务中:

```ts
import { createRuntime } from '@agentskit/runtime'
import { openai } from '@agentskit/adapters'

const runtime = createRuntime({
  adapter: openai({ apiKey: process.env.OPENAI_API_KEY!, model: 'gpt-4o' }),
  retriever: rag,
})

const result = await runtime.run('Explain the AgentsKit architecture based on ingested docs')
console.log(result.content)
```

您也可以打电话 `rag.retrieve({ query, messages })` 满足核心 `Retriever` 合同(例如来自自定义控制器).

## 特征

-   `createRAG({ embed, store })` ——摄入+取回的单入口.
-   `rag.ingest(docs)` 散装、嵌入和储存文件.
-   `rag.search(query, { topK })` ——语义相似性搜索.
-   `rag.retrieve({ query, messages })` —— 说 `Retriever` 运行时间/控制器注射合同v1.
-   可配置块 : `chunkSize`, (中文(简体) ), `chunkOverlap`,自定义 `split`。 。 。 .
-   与任何 `EmbedFn` 和任何 `VectorMemory`。 。 。 .
-   **复数 :** `createRerankedRetriever` (Voyage, Jina,习俗) `RerankFn`, BM25 默认值), `createHybridRetriever` 独立 `bm25Score`。 。 。 . [食谱](https://www.agentskit.io/docs/reference/recipes/rag-reranking)。 。 。 .
-   **文件加载器 :** `loadUrl`, (中文(简体) ), `loadGitHubFile`, (中文(简体) ), `loadGitHubTree`, (中文(简体) ), `loadNotionPage`, (中文(简体) ), `loadConfluencePage`, (中文(简体) ), `loadGoogleDriveFile`, (中文(简体) ), `loadPdf`, (中文(简体) ), `loadS3`, (中文(简体) ), `loadGcs`, (中文(简体) ), `loadDropbox`,以及 `loadOneDrive`。 。 。 . [食谱](https://www.agentskit.io/docs/reference/recipes/doc-loaders)。 。 。 .
-   **装入器韧性 :** HTTP/网络和应答机构读取/解析故障表面为 `RagError` (单位:千美元)`AK_RAG_LOAD_FAILED`) (中文(简体) ). 每一个远程请求和读取的正文都有默认的有限超时和字节限制;两者都可以通过 `timeoutMs` 财务报告和审定财务报表 `maxResponseBytes`。 。 。 . `timeoutMs` 默认为15秒,接受正安全整数可达2,147,483,647ms. 超时和可选 `signal` 中止在支持时取消获取和 HTTP 车身流 。 调用者中止不会作为每个对象的跳过被吞噬;在树/列表部分成功语义允许的情况下,可以跳过超时或其他单个非破坏失败. S3 列表/get 调用接收 SDK 中止信号, 并同步可插入对象机构接收 `return()` ; 忽略其背景的自定义延时器。 如果仅变形的S3体的变形忽视了取消,它们也可能继续. 树/列表加载器在至少一次合格下载成功时可能返回部分成功;如果每次尝试合格下载失败,它们会扔出. 缺少/无效的 S3 对象体计算为失败下载 。 假设报告更多数据时没有新的光标/托起抛出(没有静态切换) . `loadNotionPage` 随后 `has_more` 编号 : `next_cursor` 与 `start_cursor` 直到完整(保留块顺序;不完全或重复光标抛出). `loadUrl` 需要 HTTPS 来源于 `allowedOrigins`;它不遵循方向调整。 非阳性/非无限 `maxFiles` 产量 `[]`。 。 。 .
-   **记分合同:** 无分数搜索/重排结果保持顺序 。 当出现任何分数时,每个结果都必须有一个有限度的分数,并且被排序为下行——混合或非无限分数投出(绝不是编造出) `-Infinity`) 变形 Voyage/Jina/ Custom reranker 输出抛出 `AK_RAG_RERANK_FAILED`可选 `signal` 打开 `voyageReranker` 编号 : `jinaReranker` 已转发至 `fetch`; 请求/机构中止保留 `AK_RAG_RERANK_FAILED`。 。 。 . `bm25Score` 消毒无效 `k1`编号 :`b` 并总是给出有限的分数。 混合相对权重的常态化为有限度的一对,总和为一(均为0~0.5/0.5).
-   **春克/ 配置安全 :** 无效 `chunkSize` 编号 : `chunkOverlap` 编号 : `topK` 值被消毒,所以块化总是终止,搜索永远不会向商店发出非无限的限制.
-   **摄入行为 :** `rag.ingest` 按顺序嵌入并发送一个矢量存储批次。 对于大型的corpora,在呼叫器中批发文档并坚持在呼叫之间取得进展;包中不会默默地添加通量或无约束的背景队列.

### 标记下笔记( M)`@agentskit/rag/markdown`(中文(简体) )

纯度,用于知识基样式Markdown(YAML前题, `[[wikilinks]]`页:1 子路径是分开的,所以根入及其规模预算不包含 `yaml` par.

```ts
import { parseNote, findSection, parseTable } from '@agentskit/rag/markdown'

const note = parseNote('notes/plan.md', raw)
// { path, title, frontmatter, body, links, frontmatterError? }
const rows = parseTable(findSection(note.body, 'backlog')?.content ?? '')
```

也导出 : `splitFrontmatter`, (中文(简体) ), `extractWikilinks`, (中文(简体) ), `stripWikilinks`, (中文(简体) ), `sections`, (中文(简体) ), `normalize`, (中文(简体) ), `plain`。无效的前题从不丢出;在 `frontmatterError`。 。 。 .

### 博览会和回放本地运行时间中的 S3

节点消费者可以安装 `@aws-sdk/client-s3` 并让 `loadS3` 解决它懒惰。 浏览器, Expo/ Metro, 和 React Industrial 捆绑, 不让该对等方进入通用条目; 在引用加载器时明确通过命令构建器 :

```ts
import { GetObjectCommand, ListObjectsV2Command, S3Client } from '@aws-sdk/client-s3'
import { loadS3 } from '@agentskit/rag'

await loadS3({
  client: new S3Client({}),
  bucket: 'knowledge',
  commands: { GetObjectCommand, ListObjectsV2Command },
})
```

## 生态系统

| 软件包 | 作用 |
| --- | --- |
| [@ agentskit/ 核心](https://www.npmjs.com/package/@agentskit/core) | `Retriever`, (中文(简体) ), `VectorMemory`,类型 |
| [@ agentskit/ 记忆](https://www.npmjs.com/package/@agentskit/memory) | 向量后端( R)`fileVectorMemory`页:1 |
| [@ agentskit/ 适应器](https://www.npmjs.com/package/@agentskit/adapters) | `openaiEmbedder` 和其他嵌入器 |
| [@ agentskit/ 运行时间](https://www.npmjs.com/package/@agentskit/runtime) | `retriever` 代理人的融合 |
| [@ agentskit/ 反应](https://www.npmjs.com/package/@agentskit/react) | `useChat` + 以相同核心类型聊天 UI |

## 贡献者

[![AgentsKit contributors](https://contrib.rocks/image?repo=AgentsKit-io/agentskit)](https://github.com/AgentsKit-io/agentskit/graphs/contributors)

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/LICENSE)。 。 。 .

## 文档

[完整文档](https://www.agentskit.io/) • 妇女 [GitHub 图像](https://github.com/AgentsKit-io/agentskit)

## 成熟性和相容性

-   稳定性: **β 语录** 看到了吗 [文件/服务.md](https://npmcn.com/package/docs/STABILITY.md)
-   **节点.js 20+** 财务报告和审定财务报表 **类型脚本** 严格模式
-   发表于 `@agentskit/rag`

## 捐款

见 [捐款额](https://npmcn.com/package/CONTRIBUTING.md) 单曲 [自由主义](https://npmcn.com/package/LICENSE)。 。 。 .

## 分区绑定检索

`createPartitionedRAG` 编曲 `createRAG` 不更改核心检索器 合同或现有合同 `createRAG` 行为 将每个实例绑入非空格 构造时分区 :

```ts
import { createPartitionedRAG } from '@agentskit/rag'

const rag = createPartitionedRAG({
  store,
  embed,
  partition: 'team-a',
  topK: 5,
  overfetchFactor: 4,
  onDiagnostics: diagnostics => console.warn(diagnostics),
})
await rag.ingest([{ id: 'guide', content: 'Team A guide' }])
const hits = await rag.retrieve({ query: 'guide' })
```

Ingest 覆盖保留的 `_akPartition` 元数据字段和命名空间块 带有 JSON tuple 的ID, 所以不同分区的相同文档 ID 不 覆盖或删除对方的块 。 文件元数据,包括 `documentId`,继续提供。 返回的块ID是不透明的命名空间ID. 每一次搜索都有一个核心 `VectorFilter` 实现平等 本地分区元数据, 拒绝外国或缺失元数据, 即使当一个 存储忽略了过滤器。 包装器进行一个商店搜索,最多请求一次 `topK * overfetchFactor` 考生,最多考取人数,然后返回 多数 `topK` 火柴。 比赛。 该因子为从 1 到 16 (默认 4) 的整数; 不安全 候选人限制投出。 待命 `search` 限制和门槛仍然有效.

所需数额 `onDiagnostics` 每次成功的商店搜索都要回调, 包括空结果 `partition`, (中文(简体) ), `requestedTopK`, (中文(简体) ), `candidateLimit`, (中文(简体) ), `examined`, (中文(简体) ), `rejected`, (中文(简体) ), `returned`,以及 `recall: 'potentially-reduced'`这是 保守性: 边框过度可忽略匹配块, 商店可以 内部过滤一个有界限的全球候选人人才库,但不披露排除情况 (截至 `fileVectorMemory` 页:1 短期结果永远不能证明有理由归还另一个 分区块 。 回拨例外拒绝搜索 .

存储必须忠实保存块元数据和ID. 缺少元数据失败 关闭,但不能编造或错误重新分配分区元数据 检测到 这是检索隔离,不是授权边界 不受信任的作家或商店. 使用物理分离的仓库或后端 需要时信任分区执行或彻底召回. 后端-内部过度牵引在包装者候选人约束之外.

## 常见问题

### @agentskit/rag 是什么？

为"特工Kit"提供插件和游戏回取功能\.

### 如何安装 @agentskit/rag？

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

### @agentskit/rag 支持 TypeScript 吗？

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

### @agentskit/rag 支持 ESM 还是 CommonJS？

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

### @agentskit/rag 需要什么版本的 Node\.js？

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

### @agentskit/rag 可以商用吗？

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

### @agentskit/rag 的下载量有多少？

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

### @agentskit/rag 还在维护吗？

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