API 参考 - Entity Enricher 文档

API 参考

Entity Enricher REST API 让你能够以编程方式丰富实体、管理 schema 并检索记录。所有响应均为 JSON。实时进度使用服务器发送事件 (SSE)。

快速开始

通过三个步骤集成 Entity Enricher：

获取模式

GET /api/schema/saved

列出已保存的模式，或根据示例数据生成一个

富化

POST /api/single/enrich/stream

启动充实，获取用于 SSE 流式传输的作业 ID

获取结果

GET /api/records/{id}

检索完整的 enrichment record 及其结构化输出

身份验证

所有 API 端点（登录/注册除外）都需要身份验证。使用带有组织访问密钥的 X-API-Key 请求头：

curl -H "X-API-Key: ent_your_key_here" \
     https://your-instance.example.com/api/enrichment/options

在 API 密钥页面或通过 POST /api/auth/api-keys 创建 API 密钥。有关密钥类型和权限的详情，请参阅API 密钥指南。

主要端点

丰富化

方法	端点	描述
GET	/api/enrichment/options	可用的模型、语言和策略
POST	/api/single/enrich/stream	启动单个实体充实（返回用于 SSE 的 job_id）
POST	/api/single/enrich/sync	面向非 SSE 客户端（Make.com、curl）的阻塞式单条增强
POST	/api/enrichment/batch/start	为多个实体启动批量充实
POST	/api/enrichment/batch/fetch	从外部 URL 获取实体

作业管理

方法	端点	描述
GET	/api/llm/stream/{job_id}	适用于任何 LLM 作业（扩充、模式、融合）的 SSE 流
POST	/api/llm/cancel/{job_id}	取消正在运行或已暂停的作业
POST	/api/llm/continue/{job_id}	恢复已暂停的作业（例如在分类不匹配之后）

Schema

方法	端点	描述
GET	/api/schema/saved	列出所有已保存的模式
POST	/api/schema/saved	创建新架构
POST	/api/schema/generate/stream	从示例数据生成模式（SSE）
POST	/api/schema/saved/{id}/prompt/stream	使用自然语言进行 AI 模式编辑（SSE）

记录与融合

方法	端点	描述
GET	/api/records	分页并筛选列出记录
GET	/api/records/{id}	通过结构化输出获取完整的记录详情
POST	/api/records/batch-delete	删除多条记录（最多 100 条）
POST	/api/fusion/merge	合并来自多个 model 的结果

附件

方法	端点	描述
POST	/api/attachments	上传一个或多个文件（multipart/form-data）
POST	/api/attachments/base64	通过 JSON base64 上传一个文件（用于非 multipart 客户端）
GET	/api/attachments/{id}/download	下载原始文件字节
DELETE	/api/attachments/{id}	删除附件（丰富后清理）

SSE 流式传输

富集、schema 生成和融合操作使用 Server-Sent Events 实现实时进度。启动任务后获取 job_id，然后连接到 SSE 流：

SSE 事件流

data: {"type":"model_started","model":"anthropic::claude-sonnet-4-5"}

data: {"type":"expertise_completed","expertise_key":"financial","partial_result":{...}}

data: {"type":"model_completed","success":true,"result":{...},"record_id":"uuid"}

data: {"type":"completed"}

主要事件类型

事件	描述
model_started	模型处理开始
expertise_completed	一个专业领域已完成（含部分结果）
model_completed	模型已完成，返回 result、record_id 和 cost
fusion_started / fusion_completed	多模型融合生命周期事件
entity_started / entity_completed	批次专用的每实体事件（包含 entity_index）
completed	终止事件 - 关闭连接
error	发生作业级错误

Python 示例

一个完整的工作流程：列出 schema、启动扩充、流式传输结果并获取最终记录：

import httpx
import json

BASE = "https://your-instance.example.com"
KEY = "ent_your_api_key"
HEADERS = {"X-API-Key": KEY, "Content-Type": "application/json"}

# 1. List saved schemas
schemas = httpx.get(f"{BASE}/api/schema/saved", headers=HEADERS).json()
schema_id = schemas["schemas"][0]["id"]

# 2. Start enrichment
resp = httpx.post(f"{BASE}/api/single/enrich/stream", headers=HEADERS, json={
    "entity_data": {"name": "Moderna Inc", "country": "US"},
    "schema_id": schema_id,
    "models": ["anthropic::claude-sonnet-4-5-20250514"],
    "strategy": "multi_expertise",
})
job_id = resp.json()["job_id"]

# 3. Stream SSE events
record_id = None
with httpx.stream("GET", f"{BASE}/api/llm/stream/{job_id}", headers=HEADERS) as stream:
    for line in stream.iter_lines():
        if not line.startswith("data: "):
            continue
        event = json.loads(line[6:])

        if event["type"] == "model_completed" and event.get("record_id"):
            record_id = event["record_id"]
        elif event["type"] == "completed":
            break

# 4. Retrieve the enrichment record
if record_id:
    record = httpx.get(f"{BASE}/api/records/{record_id}", headers=HEADERS).json()
    print(json.dumps(record["structured_output"], indent=2))

curl 示例

使用两个模型启动批量充实并流式传输结果：

# Start batch enrichment
JOB_ID=$(curl -s -X POST \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  "$BASE/api/enrichment/batch/start" \
  -d '{
    "entities": [
      {"name": "Pfizer Inc", "country": "US"},
      {"name": "Roche", "country": "CH"}
    ],
    "schema_id": "your-schema-uuid",
    "models": ["anthropic::claude-sonnet-4-5-20250514", "openai::gpt-4o"],
    "strategy": "multi_expertise",
    "arbitration_model": "anthropic::claude-sonnet-4-5-20250514"
  }' | jq -r '.job_id')

# Stream events
curl -N -H "X-API-Key: $KEY" "$BASE/api/llm/stream/$JOB_ID"

# List resulting records
curl -s -H "X-API-Key: $KEY" \
  "$BASE/api/records?type=enrichment&page_size=10" | jq '.records'

错误处理

状态	含义	示例
200	成功	请求已完成
400	错误的请求	模型键无效或字段缺失
401	未授权	API 密钥缺失或无效
403	禁止	角色权限不足，无法访问此端点
404	未找到	未找到记录、模式或任务
500	服务器错误	内部故障