# AI-Core 文档解析服务 API 对接文档

## 服务地址

```
localhost:50051
```

## VLM 配置（可选）

VLM 用于提升图片文件的解析效果。如果不配置 VLM，则使用默认的 MarkItDown 解析。

### 方式一：环境变量

```bash
# 设置环境变量
export VLM_API_KEY="your-api-key"
export VLM_PROVIDER="openai"  # openai / anthropic / qwen
export VLM_MODEL="gpt-4o"
```

### 方式二：配置文件

在 `ai-core/config.yaml` 中配置：

```yaml
vlm:
  enabled: true
  provider: "openai"      # openai / anthropic / qwen
  model: "gpt-4o"        # 模型名称
  api_key: "sk-xxx"      # API Key
  base_url: ""           # 自定义 API 地址（可选）
  prompt: ""             # 自定义提示词（可选）
```

### 支持的 VLM 提供商

| 提供商 | 示例模型 |
|--------|----------|
| openai | gpt-4o, gpt-4o-mini |
| anthropic | claude-3-opus, claude-3-sonnet |
| qwen | qwen-vl-max, qwen2-vl-72b |

---

## gRPC API 定义

### 1. ParseDocument - 解析文档

**请求 (ParseRequest)**
```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;  // 引擎配置

  // VLM 配置（可选，优先级高于全局配置）
  VLMConfig vlm_config = 6;
}

message VLMConfig {
  bool enabled = 1;
  string provider = 2;
  string model = 3;
  string api_key = 4;
  string base_url = 5;
  string prompt = 6;
}
```

**响应 (ParseResponse)**
```protobuf
message ParseResponse {
  bool success = 1;
  string content = 2;         // Markdown 内容
  string message = 3;
  int32 content_length = 4;
  string file_type = 5;
  string parser_engine = 6;
}
```

---

## Golang 对接示例

### 基础调用（无 VLM 配置时使用 MarkItDown）

```go
req := &pb.ParseRequest{
    FileUrl:  "https://example.com/document.pdf",
    FileName: "document.pdf",
}

resp, client.ParseDocument(ctx, req)
```

### 带 VLM 配置调用

```go
req := &pb.ParseRequest{
    FileUrl:  "https://example.com/image.png",
    FileName: "image.png",
    VlmConfig: &pb.VLMConfig{
        Enabled: Provider: "open  true,
       ai",
        Model:    "gpt-4o",
        ApiKey:   "sk-xxx",
    },
}

resp, err := client.ParseDocument(ctx, req)
```

---

## 解析逻辑

1. **图片文件** (jpg, png, webp 等)
   - 如果配置了 VLM → 使用 VLM 解析
   - 如果没有配置 VLM → 使用 MarkItDown 解析

2. **PDF/DOCX/PPTX 等文档**
   - 使用 MarkItDown 解析

3. **VLM 优先级**
   - gRPC 请求中的 vlm_config > 全局配置（config.yaml/环境变量）

---

## 注意事项

1. **文件 URL**: 必须是可直接访问的 URL
2. **文件名**: 必须带扩展名（如 `.pdf`, `.png`）
3. **返回内容**: Markdown 格式文本