🍱 semantic-chunking

用于从大文本中语义化创建分块的 NPM 包。适用于涉及大语言模型（LLMs）的工作流。

维护者

特性

• 基于句子相似度的语义分块
• 动态相似度阈值
• 可配置的分块大小
• 多种嵌入模型选项
• 量化模型支持
• 为 RAG 工作流提供分块前缀支持
• 用于实验设置的 Web UI

语义分块工作流

工作原理

1. 句子分割：将输入文本分割成句子数组。
2. 嵌入生成：使用指定的 ONNX 模型为每个句子创建向量。
3. 相似度计算：计算每对句子之间的余弦相似度分数。
4. 分块形成：根据相似度阈值和最大令牌大小将句子分组为块。
5. 分块再平衡：（可选）将相似的相邻块合并成更大的块，直到达到最大令牌大小。
6. 输出：最终的分块作为对象数组返回，每个对象包含上述属性。

安装

npm install semantic-chunking

Docker 使用

运行 semantic-chunking 最简单的方法是使用 Docker Compose：

Docker Compose（推荐）

# 启动 Web UI 服务器
npm run docker:compose:up

# 在 http://localhost:3000 访问 Web UI

# 停止服务器
npm run docker:compose:down

docker-compose.yml 配置包括：
- 端口映射：3000:3000 用于 Web UI
- 卷映射：挂载 ./models 目录以在容器重启间持久化下载的嵌入模型
- 健康检查和自动重启策略

替代 Docker 命令

# 构建 Docker 镜像
npm run docker:build

# 使用 models 卷运行容器
npm run docker:run

# 或直接使用 docker-compose
docker-compose up -d

在 Docker 中使用库

要直接使用分块函数（不仅仅是 Web UI）：

# 在容器内执行 chunkit 示例
docker-compose exec semantic-chunking node example/example-chunkit.js

# 执行 cramit 示例
docker-compose exec semantic-chunking node example/example-cramit.js

# 执行 sentenceit 示例
docker-compose exec semantic-chunking node example/example-sentenceit.js

关于 Models 卷

./models 目录被挂载为卷，用于持久化下载的 ONNX 嵌入模型。模型在首次使用时自动下载，大小从 23MB 到 548MB 不等，具体取决于您选择的模型。持久化此目录意味着：
- 模型仅下载一次
- 容器重启更快
- 模型在容器更新后得以保留
- 您可以在运行 Docker 之前使用 npm run download-models 预下载模型

API 服务器使用

将 semantic-chunking 作为微服务 API 运行，以便集成到您的应用程序中。

快速开始

启动 API 服务器：

# 使用 Docker Compose（推荐）
npm run docker:compose:up

# 或在本地运行
npm run api-server

API 将在 http://localhost:3001 可用，并显示一个终端风格的登录页面，其中包含使用说明。

API 端点

• POST /api/chunkit - 基于相似度的语义分块
• POST /api/cramit - 无相似度分析的密集打包
• POST /api/sentenceit - 将文本分割成句子
• GET /api/health - 健康检查
• GET /api/version - API 版本

API 请求示例

curl -X POST http://localhost:3001/api/chunkit \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "document_name": "test",
        "document_text": "Your text here..."
      }
    ],
    "options": {
      "maxTokenSize": 500,
      "similarityThreshold": 0.5
    }
  }'

身份验证（可选）

通过设置 API_AUTH_TOKEN 环境变量启用 Bearer 令牌身份验证：

# 在 .env 文件中
API_AUTH_TOKEN=your-secret-token-here

# 或在 docker-compose.yml 中
environment:
  - API_AUTH_TOKEN=your-secret-token-here

启用后，在请求中包含令牌：

curl -X POST http://localhost:3001/api/chunkit \
  -H "Authorization: Bearer your-secret-token-here" \
  -H "Content-Type: application/json" \
  -d '...'

Docker 服务

docker-compose 配置包括两个服务：

API 服务器（默认）：

docker-compose up -d
# 在 http://localhost:3001 可用

API 服务器 + Web UI：

docker-compose --profile webui up -d
# API: http://localhost:3001
# Web UI: http://localhost:3000

完整文档

有关所有端点、请求/响应格式、错误处理和部署指南的完整 API 文档，请参阅 API.md。

使用

基本用法：

import { chunkit } from 'semantic-chunking';

const documents = [
    { document_name: "document1", document_text: "contents of document 1..." },
    { document_name: "document2", document_text: "contents of document 2..." },
    ...
];
const chunkitOptions = {};
const myChunks = await chunkit(documents, chunkitOptions);

注意 🚨 嵌入模型 (onnxEmbeddingModel) 将在首次运行时下载到此包的缓存目录中（文件大小取决于指定的模型；请参阅模型表）。

参数

chunkit 接受一个文档对象数组和一个可选的配置对象。以下是每个参数的详细信息：

• documents：文档数组。每个文档是一个包含 document_name 和 document_text 的对象。
  documents = [ { document_name: "document1", document_text: "..." }, { document_name: "document2", document_text: "..." }, ... ]

• Chunkit 选项对象：

• logging：布尔值（可选，默认 false）- 启用详细处理步骤的日志记录。

• maxTokenSize：整数（可选，默认 500）- 每个分块的最大令牌大小。
• similarityThreshold：浮点数（可选，默认 0.5）- 确定句子是否足够相似以属于同一分块的阈值。值越高要求相似度越高。
• dynamicThresholdLowerBound：浮点数（可选，默认 0.4）- 动态相似度阈值的最小可能值。
• dynamicThresholdUpperBound：浮点数（可选，默认 0.8）- 动态相似度阈值的最大可能值。
• numSimilaritySentencesLookahead：整数（可选，默认 3）- 为计算相似度而向前查看的句子数量。
• combineChunks：布尔值（可选，默认 true）- 确定是否重新平衡并将分块合并成更大的块，直到达到最大令牌限制。
• combineChunksSimilarityThreshold：浮点数（可选，默认 0.5）- 在再平衡和合并阶段基于相似度合并分块的阈值。
• onnxEmbeddingModel：字符串（可选，默认 Xenova/all-MiniLM-L6-v2）- 用于创建嵌入的 ONNX 模型。
• dtype：字符串（可选，默认 fp32）- 嵌入模型的精度（选项：fp32, fp16, q8, q4）。
• device：字符串（可选，默认 cpu）- 模型使用的执行提供程序（选项：cpu, webgpu）。
• localModelPath：字符串（可选，默认 null）- 保存和加载模型的本地路径（例如：./models）。
• modelCacheDir：字符串（可选，默认 null）- 缓存下载模型的目录（例如：./models）。
• returnEmbedding：布尔值（可选，默认 false）- 如果设置为 true，每个分块将包含一个嵌入向量。这对于需要分块语义理解的应用很有用。嵌入模型将与 onnxEmbeddingModel 中指定的相同。
• returnTokenLength：布尔值（可选，默认 false）- 如果设置为 true，每个分块将包含令牌长度。这对于理解每个分块在令牌方面的大小很有用，这对于基于令牌的处理限制很重要。令牌长度使用 onnxEmbeddingModel 中指定的分词器计算。
• chunkPrefix：字符串（可选，默认 null）- 添加到每个分块的前缀（例如："search_document: "）。这对于使用经过特定任务前缀训练的嵌入模型（如 nomic-embed-text-v1.5 模型）特别有用。前缀在计算嵌入或令牌长度之前添加。
• excludeChunkPrefixInResults：布尔值（可选，默认 false）- 如果设置为 true，分块前缀将从结果中移除。当您希望从结果中移除前缀，同时在嵌入计算中仍保留前缀时，这很有用。

输出

输出是一个分块数组，每个分块包含以下属性：

• document_id：整数 - 文档的唯一标识符（当前时间戳，毫秒）。
• document_name：字符串 - 被分块的文档名称（如果提供）。
• number_of_chunks：整数 - 从输入文本返回的最终分块总数。
• chunk_number：整数 - 当前分块的编号。
• model_name：字符串 - 使用的嵌入模型名称。
• dtype：字符串 - 使用的嵌入模型的精度（选项：fp32, fp16, q8, q4）。
• text：字符串 - 分块后的文本。
• embedding：数组 - 嵌入向量（如果 returnEmbedding 为 true）。
• token_length：整数 - 令牌长度（如果 returnTokenLength 为 true）。

注意 🚨 每个嵌入模型的行为都不同！

了解您选择的模型在对文本分块时的行为非常重要。
强烈建议使用 Web UI 调整所有参数，以便为您的用例获得最佳结果。
Web UI README

示例

示例 1：使用自定义相似度阈值的基本用法：

import { chunkit } from 'semantic-chunking';
import fs from 'fs';

async function main() {
    const documents = [ 
        {
            document_name: "test document", 
            document_text: await fs.promises.readFile('./test.txt', 'utf8') 
        }
    ];
    let myChunks = await chunkit(documents, { similarityThreshold: 0.4 });

    myChunks.forEach((chunk, index) => {
        console.log(`\n-- Chunk ${index + 1} --`);
        console.log(chunk);
    });
}
main();

示例 2：使用较小的最大令牌大小进行分块：

import { chunkit } from 'semantic-chunking';

const frogText = "A frog hops into a deli and croaks to the cashier, \"I'll have a sandwich, please.\" The cashier, surprised, quickly makes the sandwich and hands it over. The frog takes a big bite, looks around, and then asks, \"Do you have any flies to go with this?\" The cashier, taken aback, replies, \"Sorry, we're all out of flies today.\" The frog shrugs and continues munching on its sandwich, clearly unfazed by the lack of fly toppings. Just another day in the life of a sandwich-loving amphibian! 🐸🥪";
const documents = [
    {
        document_name: "frog document",
        document_text: frogText
    }
];

async function main() {
    let myFrogChunks = await chunkit(documents, { maxTokenSize: 65 });
    console.log("myFrogChunks", myFrogChunks);
}
main();

查看 example\example-chunkit.js 文件，了解使用所有可选参数的更复杂示例。

调优

可以使用选项对象中的几个可选参数来微调 chunkit 函数的行为。了解每个参数如何影响函数可以帮助您根据特定需求优化分块过程。

logging

• 类型：布尔值
• 默认值：false
• 描述：在分块过程中启用详细的调试输出。打开此选项有助于诊断分块如何形成或为什么某些分块被合并。

maxTokenSize

• 类型：整数
• 默认值：500
• 描述：设置单个分块中允许的最大令牌数。较小的值会导致更小、更多的分块，而较大的值可以创建更少、更大的分块。在处理大文本时，这对于保持可管理的分块大小至关重要。

similarityThreshold

• 类型：浮点数
• 默认值：0.456
• 描述：确定两个句子包含在同一分块中所需的最小余弦相似度。较高的阈值要求更高的相似度，可能导致更多但更小的分块，而较低的值可能导致更少、更大的分块。

dynamicThresholdLowerBound

• 类型：浮点数
• 默认值：0.2
• 描述：分块形成期间动态调整相似度阈值的最小限制。这确保动态阈值不会低于某个水平，保持分块中句子之间的基线相似度。

dynamicThresholdUpperBound

• 类型：浮点数
• 默认值：0.8
• 描述：动态调整相似度阈值的最大限制。此上限防止阈值变得过于宽松，否则可能导致块过大且内聚性低。

numSimilaritySentencesLookahead

• 类型：整数
• 默认值：2
• 描述：控制在分块形成期间，为计算与当前句子的最大相似度而考虑的后续句子数量。较高的值增加了找到合适句子以扩展当前分块的机会，但代价是增加了计算开销。

combineChunks

• 类型：布尔值
• 默认值：true
• 描述：确定是否执行第二轮处理，将较小的分块基于其语义相似度和 maxTokenSize 合并成较大的块。这可以通过更有效地分组密切相关的内容来增强输出的可读性。

combineChunksSimilarityThreshold

• 类型：浮点数
• 默认值：0.4
• 描述：在分块合并的第二轮中使用，以根据相似度决定相邻分块是否应合并。类似于 similarityThreshold，但专门用于重新平衡现有分块。调整此参数有助于微调最终分块的粒度。

onnxEmbeddingModel

• 类型：字符串
• 默认值：Xenova/all-MiniLM-L6-v2
• 描述：指定用于生成句子嵌入的模型。不同的模型可能产生不同质量的嵌入，影响分块质量，尤其是在多语言上下文中。
• 资源链接：ONNX 嵌入模型
  指向由 Xenova 转换为 ONNX 库格式的嵌入模型的过滤列表的链接。
  请参阅下面的模型表以获取建议模型及其大小的列表（如果需要分块非英语文本，请选择多语言模型）。

device

• 类型：字符串
• 默认值：cpu
• 描述：指定模型的执行提供程序。选项是 cpu 和 webgpu。使用 webgpu 以利用 GPU 加速进行更快的处理。请注意，WebGPU 支持可能因环境而异。

dtype

• 类型：字符串
• 默认值：fp32
• 描述：指示嵌入模型的精度。选项是 fp32, fp16, q8, q4。
  fp32 是最高精度，但也是最大尺寸且加载最慢。如果模型支持，q8 是尺寸和速度之间的良好折衷。所有模型都支持 fp32，但只有部分支持 fp16, q8 和 q4。

精选 ONNX 嵌入模型