مرجع API

بدء سريع

ادمج Entity Enricher في ثلاث خطوات:

المصادقة

تتطلب جميع نقاط نهاية API (باستثناء تسجيل الدخول/التسجيل) المصادقة. استخدم ترويسة X-API-Key مع مفتاح وصول المؤسسة:

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

أنشئ مفاتيح API من صفحة مفاتيح API أو عبر POST /api/auth/api-keys. راجع دليل مفاتيح API للاطلاع على تفاصيل أنواع المفاتيح والأذونات.

نقاط النهاية الرئيسية

بث SSE

تستخدم عمليات الإثراء وإنشاء المخطط والدمج تقنية Server-Sent Events لعرض التقدّم في الوقت الفعلي. ابدأ مهمة، واحصل على job_id، ثم اتصل بتدفّق SSE:

مثال Python

سير عمل كامل يسرد المخططات، ويبدأ الإثراء، ويبثّ النتائج، ويسترجع السجل النهائي:

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'

معالجة الأخطاء

تتضمن استجابات الخطأ حقل detail يحمل رسالة خطأ مقروءة للبشر. وتحمل إخفاقات الخطة والفوترة (402) إضافةً إلى ذلك جسمًا منظَّمًا يتضمن code ثابتًا — prompt_limit_reached وinsufficient_credits وmodel_limit_exceeded وbenchmarks_not_in_plan — إلى جانب أرقام الحد والاستخدام ذات الصلة، ليتمكن العميل من التفرّع بحسب السبب بدل تحليل النص. وتُصدر تدفقات SSE نوع الحدث error قبل الحدث النهائي completed إذا أخفق شيء أثناء التدفق.

المفاتيح المركبة للنموذج

تُعرَّف النماذج بمفاتيح مركّبة بالصيغة provider_name::model_name. استخدم GET /api/enrichment/options لعرض النماذج المتاحة ومفاتيحها.

معامل النموذج اختياري في الإثراء، وتوليد المخطط، وتوليد العينات: أغفِله (أو مرّر القيمة الحرفية "auto") ليختار الخادم النموذج الافتراضي لمؤسستك — الإعداد الافتراضي المثبّت لكل مهمة إن كان مضبوطًا في الإعدادات، وإلا فالنموذج ذو أفضل نتيجة إجمالية من معايير القياس المصدر للتقييم. يعرض الحقل default_models في استجابة الخيارات ما يحلّ إليه "تلقائي" حاليًا، ويبلّغ حدث SSE من نوع model_auto_selected عن الاختيار في كل مهمة. يحلّ "تلقائي" دائمًا إلى نموذج واحد (ولا يشغّل الدمج أبدًا)؛ ولأجل مسارات قابلة لإعادة الإنتاج، استمر في تمرير نماذج صريحة.

تقيّد خيارات الطلب الاختيار التلقائي: مع enable_web_search: true تُؤخذ في الاعتبار النماذج القادرة على البحث على الويب فقط (يعرض حقل default_models_web_search في استجابة الخيارات معاينةً لهذا الاختيار)، وتتطلب المرفقات الثنائية نموذجًا قادرًا على قراءتها (PDF، الرؤية، الصوت). وعندما لا يستوفي أي نموذج مؤهل القيود، يفشل الطلب بالرمز HTTP 400 no_capable_default_model بدلًا من إسقاط الخيار بصمت.

وثائق API التفاعلية

يتضمن التطبيق وثائق API تفاعلية مع أمثلة للطلبات/الاستجابات. يتطلب مصادقة المسؤول للوصول: