X-Agents/teams/ai/ai-core-api.md

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

服务地址

localhost:50051

VLM 配置（可选）

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

方式一：环境变量

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

方式二：配置文件

在 ai-core/config.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)

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)

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）

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

resp, client.ParseDocument(ctx, req)

带 VLM 配置调用

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 格式文本