138 lines
2.9 KiB
Markdown
138 lines
2.9 KiB
Markdown
|
# 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 格式文本
|