معماری سرویس استخراج اطلاعات

اجزای اصلی

این جدول ownership و رابط هر جزء را نشان می‌دهد. core-api، RabbitMQ و Object Storage وابستگی‌های بیرونی این repository هستند.

مرز سرویس در پلتفرم

این مخزن مسئول پارس و نرمال‌سازی متن خام PDF، DOCX و TXT است. core-api مالک پرونده و وضعیت محصول است؛ ai-workflow روی متن نرمال‌شده استخراج زمینه اختراع انجام می‌دهد.

• ورودی production: رویداد DocumentExtractionRequested با bucket، storage_key، checksum و metadata سند.
• worker فایل اصلی را از Object Storage دانلود می‌کند؛ خروجی terminal: completed با normalized_text_inline یا failed با error_category.
• core-api متن inline را در inbox دریافت و به‌عنوان artifact در Object Storage ذخیره می‌کند؛ سپس context.extraction.requested را به ai-workflow می‌فرستد.
• این سرویس chunking، embedding، Milvus و index برداری انجام نمی‌دهد.
• مسیر dev: POST /api/v1/dev/ingest/extract همان خط لوله intake را بدون RabbitMQ اجرا می‌کند.

flowchart TB
  user["کاربر / Frontend"]
  core["core-api<br/>مالک پرونده"]
  store[("S3 / Ceph<br/>فایل اصلی + artifact متن")]
  aw["ai-workflow<br/>استخراج زمینه اختراع"]

  user --> core
  core -->|"آپلود سند"| store

  subgraph extraction ["info-extraction — این مخزن"]
    direction LR
    docReq["RabbitMQ<br/>document.extraction.requested"]
    worker["extraction-worker<br/>LangGraph intake"]
    docResult["RabbitMQ<br/>document.extraction.completed / failed"]
    docReq --> worker --> docResult
  end

  core --> docReq
  store -->|"خواندن read-only"| worker
  docResult -->|"متن نرمال‌شده inline"| core
  core -->|"ذخیره artifact متن"| store
  core -->|"context.extraction.requested"| aw
  store -->|"خواندن متن نرمال‌شده"| aw

مسیر ناهمزمان (RabbitMQ)

در production، core-api رویداد درخواست را publish می‌کند. extraction-worker با prefetch=1 هر پیام را پردازش می‌کند و رویداد terminal را به exchange برمی‌گرداند.

• Consumer: scripts/run_event_worker.py → run_document_extraction_consumer.
• قبل از پردازش، payload با JSON Schema قرارداد v2 اعتبارسنجی می‌شود (ENABLE_EVENT_CONTRACT_VALIDATION).
• storage_key با workspace_id اعتبارسنجی می‌شود؛ checksum SHA-256 فایل دانلودشده با مقدار رویداد مقایسه می‌شود.
• خطاهای storage، timeout و internal به‌عنوان RetryableExtractionError reject می‌شوند؛ parser/validation/checksum به failed تبدیل و ack می‌شوند.
• completed شامل normalized_text_inline، text_length، pages_count و text_sha256 است؛ هیچ کلید artifact جداگانه‌ای برای متن publish نمی‌شود.

flowchart TB
  core["core-api"]
  ex[("Topic exchange<br/>patent_genie.events")]
  q["queue: document.extraction.requested<br/>prefetch=1"]
  worker["extraction-worker<br/>extraction_job.process_*"]
  s3[("S3 / Ceph<br/>read-only")]
  inbox["core.document.extraction.events"]
  validate["validate_event + artifact key + checksum"]
  intake["ingest_document<br/>LangGraph"]
  publish["publish completed / failed"]

  core -->|"DocumentExtractionRequested"| ex --> q --> worker
  s3 -->|"download_object"| worker
  worker --> validate --> intake --> publish
  publish --> ex --> inbox --> core

خط لوله LangGraph (intake)

همه مسیرها — production worker و dev ingest — از یک گراف LangGraph validate → parse → normalize عبور می‌کنند.

• validate_input: تشخیص نوع فایل (pdf/docx/txt) و اعتبارسنجی مسیر ورودی.
• parse_pdf: PyPDFLoader → PyMuPDF fallback → OCR در صورت متن کوتاه؛ repair جدول RTL در صورت نیاز.
• parse_docx / parse_txt: loader اختصاصی با هشدارهای کیفیت.
• normalize_text: نرمال‌سازی فارسی، تشخیص زبان، تحلیل script و quality metadata برای هر صفحه.
• خروجی: normalized_pages، warnings و metadata؛ full_text با join_pages_to_full_text ساخته می‌شود.

flowchart TB
  input["PDF / DOCX / TXT"]
  validate["validate_input<br/>detect file type"]
  pdf["parse_pdf<br/>native → PyMuPDF → OCR"]
  docx["parse_docx"]
  txt["parse_txt"]
  normalize["normalize_text<br/>Persian + language + quality"]
  out["normalized_pages + warnings"]
  input --> validate
  validate -->|"pdf"| pdf --> normalize
  validate -->|"docx"| docx --> normalize
  validate -->|"txt"| txt --> normalize
  normalize --> out

مسیر HTTP همزمان

FastAPI برای health، ATP، معماری و dev ingest در دسترس است. مسیر dev ingest همان intake graph را بدون RabbitMQ اجرا می‌کند.

• GET /health و GET /api/v1/health: وضعیت سرویس و وابستگی‌های RabbitMQ و object storage.
• POST /api/v1/dev/ingest/extract: multipart upload PDF/DOCX/TXT تا 50MB؛ فقط وقتی APP_ENV=local یا docker-dev باشد.
• GET /، /atp/، /architecture/: صفحات HTML فارسی برای مستندات داخلی.
• Swagger/ReDoc فقط در local، docker-dev یا با ENABLE_API_DOCS=true فعال است.

flowchart TB
  client["Client / Swagger / ATP"]
  api["FastAPI — info-extraction/api"]
  home["GET /"]
  health["GET /api/v1/health"]
  atp["GET /atp/*"]
  arch["GET /architecture/"]
  dev["POST /api/v1/dev/ingest/extract<br/>dev only"]
  intakePipeline["ingest_document<br/>LangGraph"]
  response["DevIngestResponse<br/>pages + full text + metrics"]
  client --> api
  api --> home
  api --> health
  api --> atp
  api --> arch
  api --> dev --> intakePipeline --> response

استقرار Docker Compose

Compose دو profile دارد: api برای HTTP و extraction-worker برای مصرف RabbitMQ. RabbitMQ و S3/Ceph روی شبکه external patent-genie-local باید از قبل در دسترس باشند.

• api: Dockerfile.dev، uvicorn با reload، bind-mount src/scripts/contracts، پورت پیش‌فرض 8000.
• extraction-worker: Dockerfile production، scripts/run_event_worker.py، بدون پورت عمومی.
• هر دو سرویس به rabbitmq:5672 و rgw:7480 متصل می‌شوند؛ credentialها از .env می‌آیند.
• docker-compose.dev.yml برای worker توسعه با mount قابل نوشتن src در دسترس است.

flowchart TB
  subgraph compose ["docker-compose.yml"]
    api["api (profile: api)<br/>uvicorn :8000 --reload"]
    worker["extraction-worker (profile: worker)<br/>run_event_worker.py"]
  end
  net[["external network<br/>patent-genie-local"]]
  rmq[("RabbitMQ :5672")]
  s3[("S3 / Ceph rgw:7480")]
  api --- net
  worker --- net
  net --- rmq
  net --- s3