AI语义文档切片服务 AntSK-FileChunk

AntSK-FileChunk是一个基于语义理解的智能文本切片服务，能解决传统切片方法在处理长文档时导致的语义破碎和上下文丢失问题，通过运用先进的Transformer模型进行语义分析，让每个切片在语义上的完整性和连贯性。AntSK-FileChunk核心功能包括对PDF、Word、Excel、PowerPoint及纯文本等多种文档格式的智能解析和语义感知切片，能自动识别并处理文档结构、表格和图片等特殊内容，能根据内容特性动态调整切片大小以平衡完整性和效率，提供了增强版的切片器，具备LRU+TTL智能缓存机制以提升处理速度，结合位置权重、趋势分析和全局一致性检查来进一步优化切片质量，提供多维度切片质量评估体系、完善的异常处理、性能监控和中英双语支持。AntSK-FileChunk通过RESTful API、Web界面和命令行工具提供多种交互方式，支持Docker容器化部署。

语义感知切片：依托Transformer模型实现语义理解，保证切片边界合理，避免在语义关键处分割。

多格式兼容：支持PDF、Word（.docx/.doc）、纯文本等多种文档格式，无需额外转换工具，直接处理不同类型文档。

智能文档解析：自动识别文档结构，精准提取并处理其中的表格、图片等特殊内容，保留文档原有关键信息。

自适应切片：根据内容特点动态调整切片大小，在保证语义完整的同时，兼顾处理效率，不会因切片过大或过小影响使用。

缓存机制：采用LRU缓存策略，对已计算的语义向量进行缓存，避免重复计算，大幅提升处理速度。

质量评估：建立多维度切片质量评估体系，不仅能完成切片，还能提供优化建议，帮助提升切片效果。

异常处理：拥有完善的降级策略，即便在特殊情况下，也能确保服务稳定运行，不轻易中断。

国际化支持：能处理中文和英文文档，满足不同语言环境下的使用需求，覆盖更广泛的用户群体。

RESTful API：提供完整的HTTP API接口，支持文件上传和文本直接处理，方便与其他系统集成。

Web界面：设计友好的Web操作界面，支持在线测试和配置，无需复杂操作，上手就能使用。

命令行工具：配备便捷的CLI工具，支持批量处理文档，适合需要高效处理大量文件的场景。

Docker部署：支持容器化部署，简化运维管理流程，降低部署和维护的难度。

AntSK-FileChunk快速上手指南

环境要求

• 编程语言：Python 3.8及以上版本

• 内存：建议4GB以上，确保运行流畅

• 存储：预留2GB空间，用于存放模型文件

AntSK-FileChunk安装

1、克隆项目：通过命令 git clone https://github.com/xuzeyu91/AntSK-FileChunk.git 将项目克隆到本地，然后执行 cd AntSK-FileChunk 进入项目目录。

2、安装依赖：运行 pip install -r requirements.txt，安装项目所需的依赖包。

3、启动服务：输入 python start_server.py 启动服务。

4、访问服务：服务启动后，Web界面可通过 http://localhost:8000 访问，API文档在 http://localhost:8000/docs 查看，健康检查可访问 http://localhost:8000/health。

AntSK-FileChunk快速测试

• 运行演示程序：执行 python examples/demo.py，体验切片效果。

• 使用命令行工具：输入 python scripts/cli.py --input document.pdf --output chunks.json 处理PDF文件；处理文本文件可使用 python scripts/cli.py --input text.txt --min-size 200 --max-size 1000。

AntSK-FileChunk系统架构

客户端的请求首先发送到FastAPI服务层，服务层将请求传递给语义切片器。语义切片器协调文档解析器、语义分析器、切片优化器和质量评估器工作：

• 文档解析器负责PDF、Word、文本等不同格式文档的解析。

• 语义分析器借助Transformer模型计算语义向量，进行相似度分析。

• 切片优化器开展智能合并和边界优化操作。

• 质量评估器进行连贯性评估，并生成质量报告。

核心组件

AntSK-FileChunk算法流程

1、文档解析：提取文档中的段落、表格、图片等结构化信息，为后续处理奠定基础。

2、文本预处理：清理文本中的噪声，标准化格式，进行分段处理，提升文本质量。

3、语义分析：计算段落语义向量，准确识别语义边界，确定合理的切片位置。

4、智能切片：结合语义阈值和长度约束进行切片，保证切片的语义完整性和合适长度。

5、优化处理：对过小的切片进行合并，对过大的切片进行分割，调整切片边界，优化切片效果。

6、质量评估：从连贯性、完整性、平衡性等多个指标评估切片质量，确保切片符合要求。

核心接口

1、文件处理接口：采用POST方法，路径为 /api/process-file，Content-Type设为 multipart/form-data。参数包括上传的文件（支持PDF、Word、TXT格式）和可选的配置JSON字符串。响应会返回处理结果，包含切片内容、数量、处理时间和文件信息等。

2、文本处理接口：使用POST方法，路径是 /api/process-text，Content-Type为 application/x-www-form-urlencoded。参数有要处理的文本内容和可选的配置JSON字符串。

3、配置获取接口：通过GET方法，路径为 /api/config/default，可获取默认配置信息。

配置参数说明

AntSK-FileChunk使用示例

Python SDK使用

from src.antsk_filechunk import SemanticChunker, ChunkConfig
# 基础使用
chunker = SemanticChunker()
chunks = chunker.process_file("document.pdf")

for chunk in chunks:
    print(f"内容: {chunk.content[:100]}...")
    print(f"语义得分: {chunk.semantic_score:.3f}")
    print(f"Token数: {chunk.token_count}")
    print("-" * 50)

自定义配置

# 创建自定义配置
config = ChunkConfig(
    min_chunk_size=300,
    max_chunk_size=1200,
    target_chunk_size=800,
    semantic_threshold=0.75,
    language="zh"

)
# 使用增强版切片器
from src.antsk_filechunk import EnhancedSemanticChunker
chunker = EnhancedSemanticChunker(
    config=config,
    cache_size=500,
    enable_fallback=True

)
# 启用增强功能
chunker.configure_coherence(
    position_weight_enabled=True,
    trend_analysis_enabled=True
)
# 处理文本
chunks = chunker.process_text_enhanced(text, use_cache=True)

# 获取统计信息
stats = chunker.get_comprehensive_stats()
health = chunker.health_check()

命令行使用

• 基础切片：python scripts/cli.py --input document.pdf --output result.json • 自定义参数：

python scripts/cli.py \
  --input document.pdf \
  --output result.json \
  --min-size 300 \
  --max-size 1200 \
  --semantic-threshold 0.75 \
  --language zh

• 批量处理：python scripts/cli.py --batch --input-dir ./documents --output-dir ./results

HTTP API调用

import requests
import json
# 文件上传处理
with open('document.pdf', 'rb') as f:
    files = {'file': f}
    data = {
        'config': json.dumps({
            'min_chunk_size': 300,
            'max_chunk_size': 1200,
            'semantic_threshold': 0.75
        })
    }
    response = requests.post('http://localhost:8000/api/process-file',
                           files=files, data=data)
    result = response.json()

# 文本直接处理
data = {
    'text': '这里是要处理的长文本内容...',
    'config': json.dumps({'target_chunk_size': 600})
}
response = requests.post('http://localhost:8000/api/process-text', data=data)
result = response.json()

AntSK-FileChunk应用场景配置

技术文档处理

config = ChunkConfig(
    min_chunk_size=300,
    max_chunk_size=1200,
    target_chunk_size=800,
    semantic_threshold=0.8,
    preserve_structure=True
)

新闻文章处理

config = ChunkConfig(
    min_chunk_size=150,
    max_chunk_size=600,
    target_chunk_size=350,
    semantic_threshold=0.7,
    handle_special_content=True
)

学术论文处理

config = ChunkConfig(
    min_chunk_size=400,
    max_chunk_size=2000,
    target_chunk_size=1000,
    semantic_threshold=0.75,
    preserve_structure=True
)

Docker部署AntSK-FileChunk

方式一：使用 Docker Compose（推荐）

1、克隆项目：git clone https://github.com/xuzeyu91/AntSK-FileChunk.git，然后 cd AntSK-FileChunk 进入项目目录。

2、启动服务：docker-compose up -d。

3、访问服务：Web界面可通过 http://localhost:8000 访问，API文档在 http://localhost:8000/docs 查看。

方式二：直接使用 Docker

1、构建镜像：docker build -t antsk-filechunk:latest .

2、运行容器：

docker run -d \
  --name antsk-filechunk \
  -p 8000:8000 \
  -v $(pwd)/temp:/app/temp \
  -v $(pwd)/config:/app/config \
  antsk-filechunk:latest

生产环境部署AntSK-FileChunk

带 Nginx 反向代理

启动包含 Nginx 的完整服务：docker-compose --profile with-nginx up -d

集群部署

1、初始化 Docker Swarm：docker swarm init

2、部署服务栈：docker stack deploy -c docker-compose.yml antsk-stack

配置选项

卷挂载

• 临时文件目录（必需）：-v $(pwd)/temp:/app/temp

• 配置文件目录（可选）：-v $(pwd)/config:/app/config

• 静态文件目录（可选）：-v $(pwd)/static:/app/static

健康检查

• 查看容器健康状态：docker inspect --format='{{.State.Health.Status}}' antsk-filechunk

• 手动健康检查：curl -f http://localhost:8000/health

想要获取完整的部署说明、故障排除和最佳实践，可以查看 Docker 部署文档。

AntSK-FileChunk性能指标

处理能力

• 文档解析速度：PDF格式约50页/秒，Word格式约100页/秒。

• 语义分析速度：约1000段落/秒。

• 内存使用：基础模型2GB，增强模式4GB。

• 并发支持：支持多线程处理，建议设置4-8个工作进程。

质量指标

• 语义连贯性：平均得分超过0.8。

• 切片平衡性：长度方差低于20%。

• 边界准确性：超过95%的切片边界位于段落间。