X-Agents/ai-core

AI-Core 文档解析服务

基于 Python 和 Microsoft MarkItDown 的 gRPC 文档解析服务，支持多种文件格式转换为 Markdown。

特性

• 统一解析引擎 - 使用 Microsoft MarkItDown，一个库支持所有格式
• 支持格式广泛 - PDF、DOCX、DOC、PPTX、PPT、XLSX、XLS、CSV、图片、网页等
• gRPC 接口 - 高性能、类型安全的 RPC 通信
• 依赖简单 - 只需安装 3 个核心包
• 易于部署 - 一键启动，开箱即用

项目结构

ai-core/
├── main.py                      # 服务启动入口
├── requirements.txt             # Python 依赖（仅 3 个包）
├── generate_grpc.py             # gRPC 代码生成脚本
├── start.sh                     # Linux/Mac 启动脚本
├── start.ps1                    # Windows 启动脚本
├── proto/                       # gRPC 协议定义
│   ├── document_parser.proto    # Protocol Buffers 定义
│   ├── document_parser_pb2.py  # 生成的 Python 代码
│   └── document_parser_pb2_grpc.py
├── parser/                      # 文档解析器模块
│   ├── __init__.py
│   └── parser.py               # MarkItDown 解析器
└── service/                     # gRPC 服务实现
    ├── __init__.py
    └── grpc_server.py           # gRPC 服务器

安装

1. 安装依赖

pip install -r requirements.txt

依赖包：

• grpcio - gRPC 框架
• grpcio-tools - gRPC 工具
• grpcio-reflection - gRPC 反射
• protobuf - Protocol Buffers
• requests - HTTP 请求
• markitdown - Microsoft 文档解析引擎

2. 生成 gRPC 代码

python generate_grpc.py

这会在 proto 目录下生成两个文件：

• document_parser_pb2.py
• document_parser_pb2_grpc.py

使用

方式 1: 使用启动脚本（推荐）

Windows:

.\start.ps1

Linux/Mac:

bash start.sh

方式 2: 直接运行

python main.py --port 50051 --max-workers 10

参数说明：

• --port: gRPC 服务端口（默认 50051）
• --max-workers: 最大工作线程数（默认 10）
• --log-level: 日志级别（DEBUG/INFO/WARNING/ERROR，默认 INFO）

gRPC 接口

ParseDocument

解析文档为 Markdown

message ParseRequest {
  string file_url = 1;                    // 文件 URL（必填）
  string file_name = 2;                   // 文件名（必填）
  string file_type = 3;                   // 文件类型（可选）
  string parser_engine = 4;               // 解析引擎（可选）
  map<string, string> engine_overrides = 5;// 引擎参数覆盖（可选）
}

message ParseResponse {
  bool success = 1;                       // 是否成功
  string content = 2;                      // Markdown 内容
  string message = 3;                      // 消息
  int32 content_length = 4;              // 内容长度
  string file_type = 5;                   // 文件类型
  string parser_engine = 6;               // 使用的解析引擎
}

GetSupportedFormats

获取支持的文件格式列表

GetEngines

获取可用的解析引擎列表

Go 客户端调用示例

import (
    "context"
    "log"
    
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)

func main() {
    conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatalf("Failed to connect: %v", err)
    }
    defer conn.Close()

    client := docparser.NewDocumentParserClient(conn)

    resp, err := client.ParseDocument(context.Background(), &docparser.ParseRequest{
        FileUrl:   "http://localhost:8082/files/abc123.pdf",
        FileName:  "example.pdf",
        FileType:  "pdf",
    })

    if err != nil {
        log.Fatalf("Failed to parse: %v", err)
    }

    log.Printf("Success: %v", resp.Success)
    log.Printf("Content length: %d", resp.ContentLength)
    log.Printf("Markdown content:\n%s", resp.Content)
}

支持的文件格式

类别	支持的扩展名
文档	pdf, docx, doc, pptx, ppt
表格	xlsx, xls, csv
文本	md, markdown, txt
图片	jpg, jpeg, png, gif, bmp, tiff, webp
网页	html, htm

为什么选择 MarkItDown？

1. 微软官方支持 - Microsoft 开发，持续维护
2. 格式覆盖全 - 一个库支持所有常见格式
3. 统一接口 - 无需为每种格式单独实现
4. 安装简单 - 只需 pip install markitdown
5. 性能优秀 - 基于优化的解析算法

故障排查

端口已被占用

如果提示端口 50051 已被占用，可以更换端口：

python main.py --port 50052

gRPC 代码未生成

如果提示找不到 docparser_pb2，运行：

python generate_grpc.py

依赖安装失败

确保使用 Python 3.8+：

python --version
pip --version

开发

测试解析器

from parser import Parser

parser = Parser()

# 解析文件
result = parser.parse("path/to/file.pdf")
print(result["content"])

# 解析字节内容
with open("file.pdf", "rb") as f:
    content = f.read()
result = parser.parse_bytes(content, "file.pdf")
print(result["content"])

许可证

MIT License