refactor: 重构 algorithm 为 ai-core 代码解析服务

- 新增 ai-core 目录，包含代码解析核心服务 - 添加 proto 定义、parser、service 模块 - 添加启动脚本和依赖配置 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-09 10:27:08 +08:00
parent f22f823a4a
commit 797518ec76
15 changed files with 1163 additions and 0 deletions
--- a/ai-core/README.md
+++ b/ai-core/README.md
@@ -0,0 +1,221 @@
+# 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. 安装依赖
+
+```bash
+pip install -r requirements.txt
+```
+
+依赖包：
+- `grpcio` - gRPC 框架
+- `grpcio-tools` - gRPC 工具
+- `grpcio-reflection` - gRPC 反射
+- `protobuf` - Protocol Buffers
+- `requests` - HTTP 请求
+- `markitdown` - Microsoft 文档解析引擎
+
+### 2. 生成 gRPC 代码
+
+```bash
+python generate_grpc.py
+```
+
+这会在 `proto` 目录下生成两个文件：
+- `document_parser_pb2.py`
+- `document_parser_pb2_grpc.py`
+
+## 使用
+
+### 方式 1: 使用启动脚本（推荐）
+
+**Windows:**
+```powershell
+.\start.ps1
+```
+
+**Linux/Mac:**
+```bash
+bash start.sh
+```
+
+### 方式 2: 直接运行
+
+```bash
+python main.py --port 50051 --max-workers 10
+```
+
+参数说明：
+- `--port`: gRPC 服务端口（默认 50051）
+- `--max-workers`: 最大工作线程数（默认 10）
+- `--log-level`: 日志级别（DEBUG/INFO/WARNING/ERROR，默认 INFO）
+
+## gRPC 接口
+
+### ParseDocument
+
+解析文档为 Markdown
+
+```protobuf
+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 客户端调用示例
+
+```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 已被占用，可以更换端口：
+
+```bash
+python main.py --port 50052
+```
+
+### gRPC 代码未生成
+
+如果提示找不到 `docparser_pb2`，运行：
+
+```bash
+python generate_grpc.py
+```
+
+### 依赖安装失败
+
+确保使用 Python 3.8+：
+
+```bash
+python --version
+pip --version
+```
+
+## 开发
+
+### 测试解析器
+
+```python
+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