mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 16:36:21 +02:00
240 lines
8.6 KiB
Markdown
240 lines
8.6 KiB
Markdown
|
---
|
||
|
|
layout: default
|
||
|
|
title: "مواصفات OpenAPI - المواصفات الفنية"
|
||
|
|
parent: "Arabic (Beta)"
|
||
|
|
---
|
||
|
|
|
||
|
|
# مواصفات OpenAPI - المواصفات الفنية
|
||
|
|
|
||
|
|
> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
|
||
|
|
|
||
|
|
## الهدف
|
||
|
|
|
||
|
|
إنشاء مواصفات OpenAPI 3.1 شاملة وقابلة للتطوير لواجهة TrustGraph REST API التي:
|
||
|
|
توثق جميع نقاط النهاية REST.
|
||
|
|
تستخدم `$ref` خارجية من أجل modularity وقابلية الصيانة.
|
||
|
|
تتوافق مباشرة مع كود مترجم الرسائل.
|
||
|
|
توفر مخططات دقيقة للطلبات والاستجابات.
|
||
|
|
|
||
|
|
## المصدر الموثوق
|
||
|
|
|
||
|
|
يتم تعريف واجهة برمجة التطبيقات بواسطة:
|
||
|
|
**مترجمو الرسائل**: `trustgraph-base/trustgraph/messaging/translators/*.py`
|
||
|
|
**مدير الموزع**: `trustgraph-flow/trustgraph/gateway/dispatch/manager.py`
|
||
|
|
**مدير نقطة النهاية**: `trustgraph-flow/trustgraph/gateway/endpoint/manager.py`
|
||
|
|
|
||
|
|
## هيكل الدليل
|
||
|
|
|
||
|
|
```
|
||
|
|
openapi/
|
||
|
|
├── openapi.yaml # Main entry point
|
||
|
|
├── paths/
|
||
|
|
│ ├── config.yaml # Global services
|
||
|
|
│ ├── flow.yaml
|
||
|
|
│ ├── librarian.yaml
|
||
|
|
│ ├── knowledge.yaml
|
||
|
|
│ ├── collection-management.yaml
|
||
|
|
│ ├── flow-services/ # Flow-hosted services
|
||
|
|
│ │ ├── agent.yaml
|
||
|
|
│ │ ├── document-rag.yaml
|
||
|
|
│ │ ├── graph-rag.yaml
|
||
|
|
│ │ ├── text-completion.yaml
|
||
|
|
│ │ ├── prompt.yaml
|
||
|
|
│ │ ├── embeddings.yaml
|
||
|
|
│ │ ├── mcp-tool.yaml
|
||
|
|
│ │ ├── triples.yaml
|
||
|
|
│ │ ├── objects.yaml
|
||
|
|
│ │ ├── nlp-query.yaml
|
||
|
|
│ │ ├── structured-query.yaml
|
||
|
|
│ │ ├── structured-diag.yaml
|
||
|
|
│ │ ├── graph-embeddings.yaml
|
||
|
|
│ │ ├── document-embeddings.yaml
|
||
|
|
│ │ ├── text-load.yaml
|
||
|
|
│ │ └── document-load.yaml
|
||
|
|
│ ├── import-export/
|
||
|
|
│ │ ├── core-import.yaml
|
||
|
|
│ │ ├── core-export.yaml
|
||
|
|
│ │ └── flow-import-export.yaml # WebSocket import/export
|
||
|
|
│ ├── websocket.yaml
|
||
|
|
│ └── metrics.yaml
|
||
|
|
├── components/
|
||
|
|
│ ├── schemas/
|
||
|
|
│ │ ├── config/
|
||
|
|
│ │ ├── flow/
|
||
|
|
│ │ ├── librarian/
|
||
|
|
│ │ ├── knowledge/
|
||
|
|
│ │ ├── collection/
|
||
|
|
│ │ ├── ai-services/
|
||
|
|
│ │ ├── common/
|
||
|
|
│ │ └── errors/
|
||
|
|
│ ├── parameters/
|
||
|
|
│ ├── responses/
|
||
|
|
│ └── examples/
|
||
|
|
└── security/
|
||
|
|
└── bearerAuth.yaml
|
||
|
|
```
|
||
|
|
|
||
|
|
## ربط الخدمات
|
||
|
|
|
||
|
|
### الخدمات العامة (`/api/v1/{kind}`)
|
||
|
|
`config` - إدارة التكوين
|
||
|
|
`flow` - دورة حياة التدفق
|
||
|
|
`librarian` - مكتبة المستندات
|
||
|
|
`knowledge` - نوى المعرفة
|
||
|
|
`collection-management` - بيانات وصفية للمجموعة
|
||
|
|
|
||
|
|
### الخدمات المستضافة على التدفق (`/api/v1/flow/{flow}/service/{kind}`)
|
||
|
|
|
||
|
|
**الطلب/الاستجابة:**
|
||
|
|
`agent`, `text-completion`, `prompt`, `mcp-tool`
|
||
|
|
`graph-rag`, `document-rag`
|
||
|
|
`embeddings`, `graph-embeddings`, `document-embeddings`
|
||
|
|
`triples`, `objects`, `nlp-query`, `structured-query`, `structured-diag`
|
||
|
|
|
||
|
|
**إرسال واستقبال:**
|
||
|
|
`text-load`, `document-load`
|
||
|
|
|
||
|
|
### الاستيراد/التصدير
|
||
|
|
`/api/v1/import-core` (POST)
|
||
|
|
`/api/v1/export-core` (GET)
|
||
|
|
`/api/v1/flow/{flow}/import/{kind}` (WebSocket)
|
||
|
|
`/api/v1/flow/{flow}/export/{kind}` (WebSocket)
|
||
|
|
|
||
|
|
### أخرى
|
||
|
|
`/api/v1/socket` (WebSocket متعدد)
|
||
|
|
`/api/metrics` (Prometheus)
|
||
|
|
|
||
|
|
## النهج
|
||
|
|
|
||
|
|
### المرحلة الأولى: الإعداد
|
||
|
|
1. إنشاء هيكل الدليل
|
||
|
|
2. إنشاء ملف رئيسي `openapi.yaml` مع البيانات الوصفية والخوادم والأمان
|
||
|
|
3. إنشاء مكونات قابلة لإعادة الاستخدام (أخطاء، معلمات شائعة، مخططات أمان)
|
||
|
|
|
||
|
|
### المرحلة الثانية: المخططات الشائعة
|
||
|
|
إنشاء مخططات مشتركة تستخدم عبر الخدمات:
|
||
|
|
`RdfValue`, `Triple` - هياكل RDF/ثلاثية
|
||
|
|
`ErrorObject` - استجابة الخطأ
|
||
|
|
`DocumentMetadata`, `ProcessingMetadata` - هياكل البيانات الوصفية
|
||
|
|
المعلمات الشائعة: `FlowId`, `User`, `Collection`
|
||
|
|
|
||
|
|
### المرحلة الثالثة: الخدمات العامة
|
||
|
|
لكل خدمة عامة (تكوين، تدفق، أمين مكتبة، معرفة، إدارة المجموعة):
|
||
|
|
1. إنشاء ملف مسار في `paths/`
|
||
|
|
2. إنشاء مخطط الطلب في `components/schemas/{service}/`
|
||
|
|
3. إنشاء مخطط الاستجابة
|
||
|
|
4. إضافة أمثلة
|
||
|
|
5. الإشارة من الملف الرئيسي `openapi.yaml`
|
||
|
|
|
||
|
|
### المرحلة الرابعة: الخدمات المستضافة على التدفق
|
||
|
|
لكل خدمة مستضافة على التدفق:
|
||
|
|
1. إنشاء ملف مسار في `paths/flow-services/`
|
||
|
|
2. إنشاء مخططات الطلب/الاستجابة في `components/schemas/ai-services/`
|
||
|
|
3. إضافة وثائق علامة التدفق حيثما ينطبق
|
||
|
|
4. الإشارة من الملف الرئيسي `openapi.yaml`
|
||
|
|
|
||
|
|
### المرحلة الخامسة: الاستيراد/التصدير و WebSocket
|
||
|
|
1. توثيق نقاط النهاية الأساسية للاستيراد/التصدير
|
||
|
|
2. توثيق أنماط بروتوكول WebSocket
|
||
|
|
3. توثيق نقاط نهاية استيراد/تصدير WebSocket على مستوى التدفق
|
||
|
|
|
||
|
|
### المرحلة السادسة: التحقق من الصحة
|
||
|
|
1. التحقق من الصحة باستخدام أدوات التحقق من صحة OpenAPI
|
||
|
|
2. الاختبار باستخدام واجهة Swagger UI
|
||
|
|
3. التحقق من تغطية جميع المترجمين
|
||
|
|
|
||
|
|
## اصطلاح تسمية الحقول
|
||
|
|
|
||
|
|
جميع الحقول في JSON تستخدم **kebab-case**:
|
||
|
|
`flow-id`, `blueprint-name`, `doc-limit`, `entity-limit`، إلخ.
|
||
|
|
|
||
|
|
## إنشاء ملفات المخططات
|
||
|
|
|
||
|
|
لكل مترجم في `trustgraph-base/trustgraph/messaging/translators/`:
|
||
|
|
|
||
|
|
1. **قراءة طريقة مترجم `to_pulsar()`** - يحدد مخطط الطلب
|
||
|
|
2. **قراءة طريقة مترجم `from_pulsar()`** - يحدد مخطط الاستجابة
|
||
|
|
3. **استخراج أسماء وأنواع الحقول**
|
||
|
|
4. **إنشاء مخطط OpenAPI** مع:
|
||
|
|
أسماء الحقول (kebab-case)
|
||
|
|
الأنواع (سلسلة، عدد صحيح، منطقي، كائن، مصفوفة)
|
||
|
|
الحقول المطلوبة
|
||
|
|
القيم الافتراضية
|
||
|
|
الأوصاف
|
||
|
|
|
||
|
|
### مثال لعملية التعيين
|
||
|
|
|
||
|
|
```python
|
||
|
|
# From retrieval.py DocumentRagRequestTranslator
|
||
|
|
def to_pulsar(self, data: Dict[str, Any]) -> DocumentRagQuery:
|
||
|
|
return DocumentRagQuery(
|
||
|
|
query=data["query"], # required string
|
||
|
|
user=data.get("user", "trustgraph"), # optional string, default "trustgraph"
|
||
|
|
collection=data.get("collection", "default"), # optional string, default "default"
|
||
|
|
doc_limit=int(data.get("doc-limit", 20)), # optional integer, default 20
|
||
|
|
streaming=data.get("streaming", False) # optional boolean, default false
|
||
|
|
)
|
||
|
|
```
|
||
|
|
|
||
|
|
الترجمة:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
# components/schemas/ai-services/DocumentRagRequest.yaml
|
||
|
|
type: object
|
||
|
|
required:
|
||
|
|
- query
|
||
|
|
properties:
|
||
|
|
query:
|
||
|
|
type: string
|
||
|
|
description: Search query
|
||
|
|
user:
|
||
|
|
type: string
|
||
|
|
default: trustgraph
|
||
|
|
collection:
|
||
|
|
type: string
|
||
|
|
default: default
|
||
|
|
doc-limit:
|
||
|
|
type: integer
|
||
|
|
default: 20
|
||
|
|
description: Maximum number of documents to retrieve
|
||
|
|
streaming:
|
||
|
|
type: boolean
|
||
|
|
default: false
|
||
|
|
description: Enable streaming responses
|
||
|
|
```
|
||
|
|
|
||
|
|
## الاستجابات المتدفقة
|
||
|
|
|
||
|
|
الخدمات التي تدعم التدفق تُرجع استجابات متعددة مع العلامة `end_of_stream`:
|
||
|
|
`agent`، `text-completion`، `prompt`
|
||
|
|
`document-rag`، `graph-rag`
|
||
|
|
|
||
|
|
قم بتوثيق هذا النمط في مخطط استجابة كل خدمة.
|
||
|
|
|
||
|
|
## استجابات الأخطاء
|
||
|
|
|
||
|
|
يمكن لجميع الخدمات إرجاع:
|
||
|
|
```yaml
|
||
|
|
error:
|
||
|
|
oneOf:
|
||
|
|
- type: string
|
||
|
|
- $ref: '#/components/schemas/ErrorObject'
|
||
|
|
```
|
||
|
|
|
||
|
|
حيث أن `ErrorObject` هو:
|
||
|
|
```yaml
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
type:
|
||
|
|
type: string
|
||
|
|
message:
|
||
|
|
type: string
|
||
|
|
```
|
||
|
|
|
||
|
|
## المراجع
|
||
|
|
|
||
|
|
المترجمون: `trustgraph-base/trustgraph/messaging/translators/`
|
||
|
|
تعيين الموزع: `trustgraph-flow/trustgraph/gateway/dispatch/manager.py`
|
||
|
|
توجيه نقطة النهاية: `trustgraph-flow/trustgraph/gateway/endpoint/manager.py`
|
||
|
|
ملخص الخدمة: `API_SERVICES_SUMMARY.md`
|