mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26:21 +02:00
8954fa3ad7
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.1 KiB
Markdown
239 lines
8.1 KiB
Markdown
---
|
||
layout: default
|
||
title: "מפרט OpenAPI - מפרט טכני"
|
||
parent: "Hebrew (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 מקיף ומודולרי עבור שער ה-API של TrustGraph REST, אשר:
|
||
מתעד את כל נקודות הקצה של REST
|
||
משתמש בקוד חיצוני `$ref` לצורך מודולריות ותחזוקה
|
||
מתאים ישירות לקוד מתרגם ההודעות
|
||
מספק סכימות מדויקות של בקשות/תגובות
|
||
|
||
## מקור האמת
|
||
|
||
ה-API מוגדר על ידי:
|
||
**מתרגמי הודעות**: `trustgraph-base/trustgraph/messaging/translators/*.py`
|
||
**מנהל ה-Dispatcher**: `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` - מטא-דאטה של אוסף
|
||
|
||
### שירותים המאוחסנים בתוך זרימה (Flow-Hosted Services) (`/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`
|
||
|
||
**שליחה והתעלמות (Fire-and-Forget):**
|
||
`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: הגדרה
|
||
1. צור מבנה תיקיות
|
||
2. צור את הקובץ הראשי `openapi.yaml` עם מטא-דאטה, שרתים, אבטחה
|
||
3. צור רכיבים שניתנים לשימוש חוזר (שגיאות, פרמטרים נפוצים, סכימות אבטחה)
|
||
|
||
### שלב 2: סכימות נפוצות
|
||
צור סכימות משותפות המשמשות בכל השירותים:
|
||
`RdfValue`, `Triple` - מבני RDF/טריפל
|
||
`ErrorObject` - תגובת שגיאה
|
||
`DocumentMetadata`, `ProcessingMetadata` - מבני מטא-דאטה
|
||
פרמטרים נפוצים: `FlowId`, `User`, `Collection`
|
||
|
||
### שלב 3: שירותים גלובליים
|
||
עבור כל שירות גלובלי (תצורה, זרימה, ספרן, ידע, ניהול אוסף):
|
||
1. צור קובץ נתיב ב-`paths/`
|
||
2. צור סכימת בקשה ב-`components/schemas/{service}/`
|
||
3. צור סכימת תגובה
|
||
4. הוסף דוגמאות
|
||
5. הפנה מהקובץ הראשי `openapi.yaml`
|
||
|
||
### שלב 4: שירותים המאוחסנים בתוך זרימה
|
||
עבור כל שירות המאוחסן בתוך זרימה:
|
||
1. צור קובץ נתיב ב-`paths/flow-services/`
|
||
2. צור סכימות בקשה/תגובה ב-`components/schemas/ai-services/`
|
||
3. הוסף תיעוד לדגל סטרימינג במידת הצורך
|
||
4. הפנה מהקובץ הראשי `openapi.yaml`
|
||
|
||
### שלב 5: ייבוא/ייצוא ו-WebSocket
|
||
1. תעד נקודות קצה מרכזיות לייבוא/ייצוא
|
||
2. תעד תבניות פרוטוקול WebSocket
|
||
3. תעד נקודות קצה של ייבוא/ייצוא ברמת הזרימה של WebSocket
|
||
|
||
### שלב 6: אימות
|
||
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)
|
||
סוגים (string, integer, boolean, object, array)
|
||
שדות חובה
|
||
ערכי ברירת מחדל
|
||
תיאורים
|
||
|
||
### תהליך מיפוי לדוגמה
|
||
|
||
```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`
|