# document-chunker

**Repository Path**: disneys_aladdin/document-chunker

## Basic Information

- **Project Name**: document-chunker
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-23
- **Last Updated**: 2025-12-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

项目概述

- 解析PDF，进行合理切片，写入Elasticsearch供RAG检索。
- 支持BM25关键词检索与可选向量检索（Sentence-Transformers）。

快速开始

- 安装依赖：`pip install -r requirements.txt`
- 配置环境变量：`ES_URL`（默认`http://localhost:9200`）
- 索引PDF目录：
  - `python -m chunker.indexer --pdf-dir ./pdfs --index docs --with-embeddings`
- 检索示例：
  - 关键词检索：`python -m chunker.retrieval --index docs --query "你的问题" --topk 5`
  - 向量检索：`python -m chunker.retrieval --index docs --query "你的问题" --topk 5 --vector`

切片策略

- 先按段落分割，再按句子聚合，使用令牌上限与重叠滑窗。
- 默认`max_tokens=512`，`overlap=128`，可在命令行调整。

Elasticsearch映射

- 字段：`doc_id`、`chunk_id`、`page`、`section`、`content`、`tokens`、`embedding`。
- 向量字段使用`dense_vector`，维度与所选模型一致（默认384）。

注意

- 首次使用`sentence-transformers`会下载模型，需联网。
- 若ES未启用向量检索，可仅使用BM25文本检索。

远程Embedding（OpenAI风格）

- 适用于通过统一网关调用不同厂商嵌入模型（例如聚合网关）。
- 运行示例：
  - `python -m chunker.indexer --pdf-dir ./pdfs --index docs --with-embeddings --remote-embed --openai-base-url http://your-gateway:3000 --openai-api-key sk-xxxx --openai-embed-model youtu-embedding --normalize-embeddings`
- 环境变量支持（可替代命令行参数）：`OPENAI_BASE_URL`、`OPENAI_API_KEY`、`OPENAI_EMBED_MODEL`
- 说明：索引初始化会先探测一次向量维度以创建 ES `dense_vector` 映射


# Word2MD
#### 默认情况（包含图片）图片会以 Base64 格式内嵌。
python scripts/docx2md.py input.docx output.md

#### 生成的 Markdown 中将完全剔除图片内容。
python scripts/docx2md.py input.docx output.md --no-images

#### 提取图片（依然包含图片引用）。
python scripts/docx2md.py input.docx output.md --images ./imgs