# @absolutejs/rag 中文文档

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

版本：0\.24\.9
npm 元数据更新时间：2026-11-03T14:51:45.388Z
中文译文更新时间：2026-11-06T02:15:05.930Z
软件包许可：BSL-1\.1

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

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

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

- 包体积（解压后）：79.3 MB，193 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- peer 依赖：vue ^3\.5\.27，react ^19\.2\.0，elysia ^2\.0\.0-beta\.6，svelte ^5\.35\.2，@angular/core ^21\.0\.0，@absolutejs/ai \>=0\.2\.7 \<0\.3，playwright-core ^1\.60\.0，@absolutejs/sync \>=2\.14\.0 \<4
- 首次发布：2026-04-22T03:17:14.580Z
- 最新版本发布：2026-11-03T14:51:44.914Z
- 近 30 天下载量：6605（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：88（近 12 个月 88 个）

## 中文简介

从绝对JS提取的独立RAG摄取、同步、检索、评价、客户端和框架适配器

## 安装

```sh
npm install @absolutejs/rag
```

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

## README

# @absolutejs/ 破损

用于 Bun 和 Elysia 应用程序的独立 RAG 运行时间,涵盖文档摄取,块化,嵌入,混合检索,重排,源同步,评价,客户端原始,以及框架绑定.

## 安装

```sh
bun add @absolutejs/rag
```

## 快开始

```ts
import {
    createInMemoryRAGStore,
    createRAGCollection,
    ingestRAGDocuments,
    openaiEmbeddings,
    searchDocuments
} from '@absolutejs/rag';

const collection = createRAGCollection({
    embedding: openaiEmbeddings({
        apiKey: process.env.OPENAI_API_KEY ?? '',
        defaultModel: 'text-embedding-3-small'
    }),
    store: createInMemoryRAGStore()
});

await ingestRAGDocuments(collection, {
    documents: [{ id: 'intro', text: 'AbsoluteJS ships typed Bun primitives.' }]
});

const results = await searchDocuments(collection, {
    query: 'What does AbsoluteJS ship?',
    topK: 3
});
```

## 检索和储存

内置记忆库支持开发和测试. 已发布的适配器为 PostgreSQL 提供 pgvector , SQLite 提供可选 vec0 加速度, 以及 Pinecone 在同一加速度之后 `RAGVectorStore` 合同。 线性结果和矢量结果可以被连接,被转化,并被提供方或高压再排行器重新排序.

### 检索频道要求

光谱和混合检索需要安装一个存储器 `queryLexical`。 。 。 . 没有这种能力的后端会在向量前产生可操作错误 嵌入/ 搜索, 而不是默回只向量或空结果 . 明确的矢量检索仍然支持在只使用矢量的后端上. 配置 请求混合检索前的可读性适配器; 模式旗 不添加缺失后端能力 .

内置的heuristic 策略保留了请求的检索模式 当一个 查询按来源或文件ID进行。 范围缩小了可搜索的物证; 它并不消除在该实体内准确关键字匹配的必要性.

## 摄入和源同步

摄取管道处理文件、目录、上传、URL、PDF、办公文件、档案、图像和媒体记录。 已排定的连接器可以从电子邮件,GitHub,站点地图,feed,目录和S3兼容存储中保持集合同步.

Feed, sitemap和 site-discovery 同步源使用受限, DNS 绑定的公众 通过最终文件摄入进行网络运输。 私人地址和不安全 重新定向目的地被拒绝 。 现场发现表明 `AbsoluteJSReader/1.0`遵守特工专用机器人的规则, `Allow`,通配符 和查询路径,并检查每个页面根据目的地政策重定向. 机器人4xx响应允许爬行,除了429;网络错误,429和5xx 在调和前中止同步, 保存先前索引文档 . 机器人政策只在同步运行中缓存 。 信任的主机可以注入 `fetchResource` 用于孤立阅读器或确定测试;适配器必须 保存 DNS 平接、 响应界限和重定向验证 。 直接 URL 和 GitHub 同步行为没有改变 。 持续的日程安排和全体爬行 预算仍然与这些来源一级的保护分开.

PDF上传使用内置的PDF.js读取器解码压缩流并 字体编码,在本地文本块中保留页码用于引用. 读者按顺序处理页面,而不强制应用 输入页数或字符限制。 上传/存储预算和模式背景 预算属于各自的层次; RAG 将提取的文本块为 检索而不是将整个PDF发送到一个模型.

扫描或仅图像 PDF 需要通过 OCR 明确配置 `createRAGPDFOCRExtractor({ provider })`。空文本层在 默认提取器 。 无效或受密码保护的文档传播读取器 出错; 不从原始 PDF 运算符进行索引 。 包括PDF工人 在服务器包中,包括编译的 Bun 应用程序.

## 质量和评价

`@absolutejs/rag/quality` 评估检索的相关性并回答置地,比较策略和重排,记录会按基线运行,这样检索更改可以在发布前测试.

## 客户和框架切入点

-   `@absolutejs/rag/client` 财务报告和审定财务报表 `/client/ui` 提供浏览器侧式原始.
-   `@absolutejs/rag/react`, (中文(简体) ), `/vue`, (中文(简体) ), `/svelte`,以及 `/angular` 提供框架约束.
-   `@absolutejs/rag/adapter-kit` 暴露了矢量存储适配器所使用的合同.
-   `@absolutejs/rag/ui` 揭露了呈报中立的UI合同.

对等检索运行时间 `@absolutejs/ai` 当检索到上下文时,应当输入一个模型或流动助手.

### 逐字记录正文证据

使用 `chunkRAGOriginalText({ sourceId, version, text }, options)` 引用时 必须解决无法改变的正本问题。 此选入路径保留 白空间和Unicode,而不是使文档格式正常化或提取. 每个块包括: `metadata.sourceLocator` 源代码,不可更改 版本和 UTF-16 `start`编号 :`end` 页:1. `readRAGOriginalText` 验证身份, 版本和范围,然后返回准确的原始切片。 储存和授权 ; 定位器不是访问补助金.

`createRAGOriginalTextTools({ collection, filter, loadSource, budget })` 提供 `search_text_source` 财务报告和审定财务报表 `read_text_source` AI工具. 它请求真正的混合 以多样性检索并对照原件核实证据. `filter` 是一个 服务器自有范围; `loadSource(id, version)` 必须重新授权每个读取和 返回时 `null` 用于无法访问/删除的版本。 这些工具需要 `budget: { maxTokens, countTokens }` 使用模型标识器和预算 由大赦国际上下文政策保留。 整个段落在其中选定 预算;省略段落被标出,而不是无声地截取。 添加 在为示范请求编制预算之前的最后工具/指示。 搜索线索是 可通过 `onTrace`;它们包含检索元数据,不应是 将批发复制到公共日志中。 服务器可能设置 `searchTopK` 改为整数 (a) 从1起到48起(默认12起),用于较小的初步证据查询。 候选人排名 仍然考虑多达48个匹配;授权和象征性预算检查是 不变。 最初的一套小结果不能确定其他事实是: 不存在:保留更广泛的搜索/阅读工具,以查找缺失或模糊的证据.

关键词匹配使用Unicode字分解和犬科正常化. 英语后缀规则仅适用于ASCII单词. 这能改进多语种精确度 匹配;它不取代对所选嵌入模型的评价.

#### AI 上下文政策兼容性

随着AI 0.1上下文政策发布,RAG聊天验证了最终组装 每个模型请求前的检索上下文 。 内容 `contextPolicy` 配置为 转发给 WebSocket 和 SSE 世代 。 使用工作符号目标或 酌情保存源恢复回调 。 没有能力的供应商 支持需要明确 `contextPolicy: false` 原始选择退出。 受支助的老年人 AI同行保留他们以前的行为;升级RAG单不会添加AI 6.1 能力政策。 RAG中没有定义模型容量编号.

### 倒数引用引用

`createRAGQuoteReferences()` 创建用于压缩的请求范围登记册 已经验证的正本文本工具结果. `encodeToolResult(json)` 替换 带有句子条目的段落文本 `{ citation, text }`· ; `resolve(citation)` 恢复准确的注册句子。 重复的句子重用一个引用, 和不明的参考文献。 搜索和单程读取的信封 支持;未识别的工具结果通过不变.

保持登记册在预留、查找和补全之间存活,然后丢弃 这个 只有编码服务器拥有的原始文本工具结果. 参考资料不是 访问控制或持久源 ID: 重新授权并验证已恢复的引用 在保存结果之前, 这是选入; 不变 原始文本工具、存储的正本或现有结果格式.

### 公共网站和 JavaScript 渲染

`loadRAGDocumentFromURL` 装入文档; 使用 `prepareRAGDocument(doc).normalizedText` 用于可读文本。 URL 加载现在在无扩展的 URL 上尊重响应 MIME 类型 . 对于公共网站, `@absolutejs/rag/web` 提供 `readRAGWebpage` 带边框 回复、超时、准备的文本、最后URL、标题、截取和每一次尝试 检索诊断。 它首先尝试静态的 HTML 并请求浏览器进行瘦化 或空应用程序外壳。 缺少渲染器返回 `rendering_required`, (中文(简体) ), 而不是声称网站没有信息.

```ts
import { readRAGWebpage } from '@absolutejs/rag/web';
import { createPlaywrightWebRenderer } from '@absolutejs/rag/web/playwright';

const browser = createPlaywrightWebRenderer();
try {
  const page = await readRAGWebpage({
    url: 'https://example.com',
    render: browser.render,
  });
  // Check page.status and page.error before treating page.text as complete evidence.
} finally {
  await browser.close();
}
```

浏览器适配器需要可选 `playwright-core` 端点和已安装 铬浏览器( C)`playwright-core install --with-deps chromium`) (中文(简体) ). 主办方应 在单独的非特权进程中运行, 限制货币, 并应用内存 限制。 上下文不共享 cookie; 服务工作者和 WebSockets 被屏蔽 . HTTP 资源及重定向跳动使用 DNS 验证的公共目的地 答对了每个连接。 浏览器资源计数和响应大小为 范围。 读者不会绕过登录、CAPTCHA或访问限制,以及 报告这些失败和不完全渲染。 读取的页面不是 一个域上的每个页面的爬行。 提供主机的渲染器/牵引执行 必须执行等同的网络控制.

### 研究相关网页及可归属证据

`readRAGWebsite` 从 `@absolutejs/rag/web` 默认读取可达8页,平衡 同一来源的客户、服务和公司网页,因此服务细节不 被大型案例档案所饿死. 可配置的上限为12页; 总期限为75秒,默认文本预算为48 000个字符。 通过 可选的 Playwright 渲染器 `readRAGWebpage`。 。 。 . `maxPages: 1` 保留a 单页读取; `mode: "browser"` 重试静态提取遗漏的内容 . 结果将文本归属于准确的页面URL并保留每页重定向, 检索尝试、语义图像标签、链接目的地、媒体 URL和 可用标题文本。 覆盖范围包括未访问的相关链接和最后期限 限制. `incompleteReads` 识别失败、部分页码或短页符; 未访问的链接和成功的浏览器回落不会被读取 . `stopReason` 区分页数限制、截止日期和已用尽的相关链接. 当一个实质问题依然存在时,不得停止研究 采用有针对性的后续行动。 先提供业务答案,并保持技术 用于明确调试请求的诊断。 HTTP 重定向显示其实际状态; 客户端导航标记 分别。 空图像标签不是客户端列表的证明, 媒体 URL不是视频被观看的证据. 消费者必须引用源 URL, 将提取的证据与推论区分开来,完成所要求的研究 而不将成功的页面获取视为完整的公司覆盖.

网站成果也与 `sources` 包含每个可读页面的数组 `title`, (中文(简体) ), `url` 并随时使用 `citation`,该页面旁边重复 证据文本。 失败的页面和未访问的链接不是可读源条目 . `citationRequirements` 要求消费者将链接放置在支持的债权旁边, 避免无根据的排除或所有权关系,并保持经核实的品牌 变化简介。 主机应用程序仍然控制着它们生成的最终答案.

`kind: "website_evidence"` 确定网站研究成果. `documents` 将每个被绑定的文本节录绑入源代码,而源条目提供 压缩编号 `inlineCitation` 链接。 这样可让适配器显示源本地 将原始检索元数据输入模型的反应范围. 合并文件案文尊重 `maxChars`;短篇节选被标出.

### 扫描和混合PDF

`createRAGPagedPDFExtractor({ provider, signal, onProgress })` 保护本地 文本页面, 并逐一发送带有图像的页面到已配置的 `RAGOCRProvider`。它也处理有可见绘图操作的页面,但没有 可提取文本。 此抓取可读文档中的扫描; a 长嵌入式标题不会使被扫描的身体跳过。 页码 并且每个提取出的文件仍附有原生/OCR出处。 土著 oCR省略的文字与抄录一起保留.

供应商收到有效的一页 PDF 外加其原件 `pageNumber` 财务报告和审定财务报表 `pageCount` 在元数据中。 主机拥有证书、计量和模型输出 限制; 提供者必须拒绝截断的答复。 页面失败拒绝 而不是报告不完整的文档为完整. `signal` 在页面之间和OCR之后检查;将同一信号传递到 供应商将取消其飞行请求. `onProgress` 报告完成后页. 空页被跳过;一个完全无法读取的文档被拒绝 .

`createWebsiteReaderClient` 从 `@absolutejs/rag/web` 连接到一个可信任的主机管理的阅读器服务,并验证其状态,文本,源 URL和限制. 配置服务端点并注入静态回落. 客户端在一个总期限内预留后退时间,宣传取消呼叫者,并保持服务饱和性可重新试用. RAG的公用HTTP/HTTPS读取器共享低等被绑定的运输方式 `@absolutejs/egress/transport`; Egress仍然执行自己的被允许的HTTPS政策.

## 网络研究工作流程

见 [研究.md](https://npmcn.com/package/%40absolutejs/rag/RESEARCH.md) 用于研究插件、六个框架流量、计划提取、实地证据审查、公司发现、耐用批次、监测、支出政策、代理工具和评价.

## 常见问题

### @absolutejs/rag 是什么？

从绝对JS提取的独立RAG摄取、同步、检索、评价、客户端和框架适配器

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

在项目目录运行 npm install @absolutejs/rag，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：elysia（^2\.0\.0-beta\.6）、@absolutejs/ai（\>=0\.2\.7 \<0\.3）、@absolutejs/sync（\>=2\.14\.0 \<4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

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

@absolutejs/rag 使用 BSL-1\.1 许可。声明的许可为 BSL-1\.1，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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