mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 16:36:21 +02:00
f95fd4f052
Native CLI i18n: The TrustGraph CLI has built-in translation support that dynamically loads language strings. You can test and use different languages by simply passing the --lang flag (e.g., --lang es for Spanish, --lang ru for Russian) or by configuring your environment's LANG variable. Automated Docs Translations: This PR introduces autonomously translated Markdown documentation into several target languages, including Spanish, Swahili, Portuguese, Turkish, Hindi, Hebrew, Arabic, Simplified Chinese, and Russian.
239 lines
8.6 KiB
Markdown
239 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`
|