mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26: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
11 KiB
Markdown
239 lines
11 KiB
Markdown
---
|
|
layout: default
|
|
title: "OpenAPI विनिर्देश - तकनीकी विनिर्देश"
|
|
parent: "Hindi (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.
|
|
|
|
## लक्ष्य
|
|
|
|
ट्रस्टग्राफ REST API गेटवे के लिए एक व्यापक, मॉड्यूलर OpenAPI 3.1 विनिर्देश बनाना जो:
|
|
सभी REST एंडपॉइंट्स का दस्तावेजीकरण करता है
|
|
मॉड्यूलरिटी और रखरखाव के लिए बाहरी `$ref` का उपयोग करता है
|
|
सीधे संदेश अनुवाद कोड से मेल खाता है
|
|
सटीक अनुरोध/प्रतिक्रिया स्कीमा प्रदान करता है
|
|
|
|
## सत्य का स्रोत
|
|
|
|
API को निम्नलिखित द्वारा परिभाषित किया गया है:
|
|
**संदेश अनुवादक**: `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: सेटअप
|
|
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 फ़ील्ड **केबाब-केस** का उपयोग करते हैं:
|
|
`flow-id`, `blueprint-name`, `doc-limit`, `entity-limit`, आदि।
|
|
|
|
## स्कीमा फ़ाइलें बनाना
|
|
|
|
प्रत्येक अनुवादक के लिए `trustgraph-base/trustgraph/messaging/translators/`:
|
|
|
|
1. **अनुवादक `to_pulsar()` विधि पढ़ें** - अनुरोध स्कीमा को परिभाषित करता है
|
|
2. **अनुवादक `from_pulsar()` विधि पढ़ें** - प्रतिक्रिया स्कीमा को परिभाषित करता है
|
|
3. **फ़ील्ड नाम और प्रकार निकालें**
|
|
4. **OpenAPI स्कीमा बनाएं** जिसमें:
|
|
फ़ील्ड नाम (केबाब-केस)
|
|
प्रकार (स्ट्रिंग, पूर्णांक, बूलियन, ऑब्जेक्ट, सरणी)
|
|
आवश्यक फ़ील्ड
|
|
डिफ़ॉल्ट
|
|
विवरण
|
|
|
|
### उदाहरण मैपिंग प्रक्रिया
|
|
|
|
```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`
|