mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-28 09:56:22 +02:00
Structure the tech specs directory (#836)
Tech spec some subdirectories for different languages
This commit is contained in:
cybermaggedon
GitHub
parent
48da6c5f8b
commit
e7efb673ef
423 changed files with 0 additions and 0 deletions
135
docs/tech-specs/hi/__TEMPLATE.hi.md
Normal file
135
docs/tech-specs/hi/__TEMPLATE.hi.md
Normal file
|
|
@ -0,0 +1,135 @@
|
|||
---
|
||||
layout: default
|
||||
title: "कमांड-लाइन लोडिंग नॉलेज टेक्निकल स्पेसिफिकेशन"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# कमांड-लाइन लोडिंग नॉलेज टेक्निकल स्पेसिफिकेशन
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह स्पेसिफिकेशन ट्रस्टग्राफ में नॉलेज लोड करने के लिए कमांड-लाइन इंटरफेस का वर्णन करता है, जो उपयोगकर्ताओं को कमांड-लाइन टूल के माध्यम से विभिन्न स्रोतों से डेटा प्राप्त करने में सक्षम बनाता है। एकीकरण चार प्राथमिक उपयोग मामलों का समर्थन करता है:
|
||||
|
||||
1. **[उपयोग मामला 1]**: [विवरण]
|
||||
2. **[उपयोग मामला 2]**: [विवरण]
|
||||
3. **[उपयोग मामला 3]**: [विवरण]
|
||||
4. **[उपयोग मामला 4]**: [विवरण]
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
- **[लक्ष्य 1]**: [विवरण]
|
||||
- **[लक्ष्य 2]**: [विवरण]
|
||||
- **[लक्ष्य 3]**: [विवरण]
|
||||
- **[लक्ष्य 4]**: [विवरण]
|
||||
- **[लक्ष्य 5]**: [विवरण]
|
||||
- **[लक्ष्य 6]**: [विवरण]
|
||||
- **[लक्ष्य 7]**: [विवरण]
|
||||
- **[लक्ष्य 8]**: [विवरण]
|
||||
|
||||
## पृष्ठभूमि
|
||||
|
||||
[वर्तमान स्थिति और सीमाओं का वर्णन करें जिन्हें यह स्पेसिफिकेशन संबोधित करता है]
|
||||
|
||||
वर्तमान सीमाओं में शामिल हैं:
|
||||
- [सीमा 1]
|
||||
- [सीमा 2]
|
||||
- [सीमा 3]
|
||||
- [सीमा 4]
|
||||
|
||||
यह स्पेसिफिकेशन इन कमियों को [विवरण] द्वारा संबोधित करता है। [क्षमता] के माध्यम से, ट्रस्टग्राफ:
|
||||
- [लाभ 1]
|
||||
- [लाभ 2]
|
||||
- [लाभ 3]
|
||||
- [लाभ 4]
|
||||
|
||||
## तकनीकी डिजाइन
|
||||
|
||||
### आर्किटेक्चर
|
||||
|
||||
कमांड-लाइन नॉलेज लोडिंग के लिए निम्नलिखित तकनीकी घटकों की आवश्यकता होती है:
|
||||
|
||||
1. **[घटक 1]**
|
||||
- [घटक कार्यक्षमता का विवरण]
|
||||
- [मुख्य विशेषताएं]
|
||||
- [एकीकरण बिंदु]
|
||||
|
||||
मॉड्यूल: [मॉड्यूल-पाथ]
|
||||
|
||||
2. **[घटक 2]**
|
||||
- [घटक कार्यक्षमता का विवरण]
|
||||
- [मुख्य विशेषताएं]
|
||||
- [एकीकरण बिंदु]
|
||||
|
||||
मॉड्यूल: [मॉड्यूल-पाथ]
|
||||
|
||||
3. **[घटक 3]**
|
||||
- [घटक कार्यक्षमता का विवरण]
|
||||
- [मुख्य विशेषताएं]
|
||||
- [एकीकरण बिंदु]
|
||||
|
||||
मॉड्यूल: [मॉड्यूल-पाथ]
|
||||
|
||||
### डेटा मॉडल
|
||||
|
||||
#### [डेटा मॉडल 1]
|
||||
|
||||
[डेटा मॉडल और संरचना का विवरण]
|
||||
|
||||
उदाहरण:
|
||||
```
|
||||
[Example data structure]
|
||||
```
|
||||
|
||||
यह दृष्टिकोण निम्नलिखित की अनुमति देता है:
|
||||
- [लाभ 1]
|
||||
- [लाभ 2]
|
||||
- [लाभ 3]
|
||||
- [लाभ 4]
|
||||
|
||||
### एपीआई (APIs)
|
||||
|
||||
नए एपीआई (APIs):
|
||||
- [एपीआई विवरण 1]
|
||||
- [एपीआई विवरण 2]
|
||||
- [एपीआई विवरण 3]
|
||||
|
||||
संशोधित एपीआई (APIs):
|
||||
- [संशोधित एपीआई 1] - [परिवर्तनों का विवरण]
|
||||
- [संशोधित एपीआई 2] - [परिवर्तनों का विवरण]
|
||||
|
||||
### कार्यान्वयन विवरण
|
||||
|
||||
[कार्यान्वयन दृष्टिकोण और परंपराएं]
|
||||
|
||||
[अतिरिक्त कार्यान्वयन नोट्स]
|
||||
|
||||
## सुरक्षा संबंधी विचार
|
||||
|
||||
[इस कार्यान्वयन के लिए विशिष्ट सुरक्षा संबंधी विचार]
|
||||
|
||||
## प्रदर्शन संबंधी विचार
|
||||
|
||||
[प्रदर्शन संबंधी विचार और संभावित बाधाएं]
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
[परीक्षण दृष्टिकोण और रणनीति]
|
||||
|
||||
## माइग्रेशन योजना
|
||||
|
||||
[यदि लागू हो, तो माइग्रेशन रणनीति]
|
||||
|
||||
## समयरेखा
|
||||
|
||||
[यदि निर्दिष्ट किया गया है, तो समयरेखा जानकारी]
|
||||
|
||||
## अनुत्तरित प्रश्न
|
||||
|
||||
- [अनुत्तरित प्रश्न 1]
|
||||
- [अनुत्तरित प्रश्न 2]
|
||||
|
||||
## संदर्भ
|
||||
|
||||
[यदि लागू हो, तो संदर्भ]
|
||||
280
docs/tech-specs/hi/agent-explainability.hi.md
Normal file
280
docs/tech-specs/hi/agent-explainability.hi.md
Normal file
|
|
@ -0,0 +1,280 @@
|
|||
---
|
||||
layout: default
|
||||
title: "एजेंट स्पष्टता: उत्पत्ति रिकॉर्डिंग"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# एजेंट स्पष्टता: उत्पत्ति रिकॉर्डिंग
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
रिएक्ट एजेंट लूप में उत्पत्ति रिकॉर्डिंग जोड़ें ताकि एजेंट सत्रों को ट्रैक और डीबग किया जा सके, जो कि ग्राफआरएजी के समान स्पष्टता बुनियादी ढांचे का उपयोग करके किया जा सके।
|
||||
|
||||
**डिजाइन निर्णय:**
|
||||
`urn:graph:retrieval` (सामान्य स्पष्टता ग्राफ) में लिखें
|
||||
फिलहाल रैखिक निर्भरता श्रृंखला (विश्लेषण N → wasDerivedFrom → विश्लेषण N-1)
|
||||
उपकरण अपार ब्लैक बॉक्स हैं (केवल इनपुट/आउटपुट रिकॉर्ड करें)
|
||||
डीएजी समर्थन भविष्य के पुनरावृत्ति के लिए स्थगित है
|
||||
|
||||
## इकाई प्रकार
|
||||
|
||||
ग्राफआरएजी और एजेंट दोनों ही ट्रस्टग्राफ-विशिष्ट उपप्रकारों के साथ पीआरओवी-ओ को आधार ऑन्टोलॉजी के रूप में उपयोग करते हैं:
|
||||
|
||||
### ग्राफआरएजी प्रकार
|
||||
| इकाई | पीआरओवी-ओ प्रकार | टीजी प्रकार | विवरण |
|
||||
|--------|-------------|----------|-------------|
|
||||
| प्रश्न | `prov:Activity` | `tg:Question`, `tg:GraphRagQuestion` | उपयोगकर्ता का प्रश्न |
|
||||
| अन्वेषण | `prov:Entity` | `tg:Exploration` | ज्ञान ग्राफ से प्राप्त किनारे |
|
||||
| फोकस | `prov:Entity` | `tg:Focus` | तर्क के साथ चयनित किनारे |
|
||||
| संश्लेषण | `prov:Entity` | `tg:Synthesis` | अंतिम उत्तर |
|
||||
|
||||
### एजेंट प्रकार
|
||||
| इकाई | पीआरओवी-ओ प्रकार | टीजी प्रकार | विवरण |
|
||||
|--------|-------------|----------|-------------|
|
||||
| प्रश्न | `prov:Activity` | `tg:Question`, `tg:AgentQuestion` | उपयोगकर्ता का प्रश्न |
|
||||
| विश्लेषण | `prov:Entity` | `tg:Analysis` | प्रत्येक सोच/कार्य/अवलोकन चक्र |
|
||||
| निष्कर्ष | `prov:Entity` | `tg:Conclusion` | अंतिम उत्तर |
|
||||
|
||||
### दस्तावेज़ आरएजी प्रकार
|
||||
| इकाई | पीआरओवी-ओ प्रकार | टीजी प्रकार | विवरण |
|
||||
|--------|-------------|----------|-------------|
|
||||
| प्रश्न | `prov:Activity` | `tg:Question`, `tg:DocRagQuestion` | उपयोगकर्ता का प्रश्न |
|
||||
| अन्वेषण | `prov:Entity` | `tg:Exploration` | दस्तावेज़ भंडार से प्राप्त टुकड़े |
|
||||
| संश्लेषण | `prov:Entity` | `tg:Synthesis` | अंतिम उत्तर |
|
||||
|
||||
**ध्यान दें:** दस्तावेज़ आरएजी ग्राफआरएजी के प्रकारों का एक उपसमुच्चय का उपयोग करता है (कोई फोकस चरण नहीं है क्योंकि कोई किनारा चयन/तर्क चरण नहीं है)।
|
||||
|
||||
### प्रश्न उपप्रकार
|
||||
|
||||
सभी प्रश्न इकाइयों में `tg:Question` को एक आधार प्रकार के रूप में साझा किया जाता है, लेकिन पुनर्प्राप्ति तंत्र की पहचान करने के लिए एक विशिष्ट उपप्रकार होता है:
|
||||
|
||||
| उपप्रकार | यूआरआई पैटर्न | तंत्र |
|
||||
|---------|-------------|-----------|
|
||||
| `tg:GraphRagQuestion` | `urn:trustgraph:question:{uuid}` | ज्ञान ग्राफ आरएजी |
|
||||
| `tg:DocRagQuestion` | `urn:trustgraph:docrag:{uuid}` | दस्तावेज़/टुकड़ा आरएजी |
|
||||
| `tg:AgentQuestion` | `urn:trustgraph:agent:{uuid}` | रीएक्ट एजेंट |
|
||||
|
||||
यह सभी प्रश्नों को `tg:Question` के माध्यम से क्वेरी करने की अनुमति देता है, जबकि उपप्रकार के माध्यम से विशिष्ट तंत्र द्वारा फ़िल्टर किया जा सकता है।
|
||||
|
||||
## उत्पत्ति मॉडल
|
||||
|
||||
```
|
||||
Question (urn:trustgraph:agent:{uuid})
|
||||
│
|
||||
│ tg:query = "User's question"
|
||||
│ prov:startedAtTime = timestamp
|
||||
│ rdf:type = prov:Activity, tg:Question
|
||||
│
|
||||
↓ prov:wasDerivedFrom
|
||||
│
|
||||
Analysis1 (urn:trustgraph:agent:{uuid}/i1)
|
||||
│
|
||||
│ tg:thought = "I need to query the knowledge base..."
|
||||
│ tg:action = "knowledge-query"
|
||||
│ tg:arguments = {"question": "..."}
|
||||
│ tg:observation = "Result from tool..."
|
||||
│ rdf:type = prov:Entity, tg:Analysis
|
||||
│
|
||||
↓ prov:wasDerivedFrom
|
||||
│
|
||||
Analysis2 (urn:trustgraph:agent:{uuid}/i2)
|
||||
│ ...
|
||||
↓ prov:wasDerivedFrom
|
||||
│
|
||||
Conclusion (urn:trustgraph:agent:{uuid}/final)
|
||||
│
|
||||
│ tg:answer = "The final response..."
|
||||
│ rdf:type = prov:Entity, tg:Conclusion
|
||||
```
|
||||
|
||||
### दस्तावेज़ आरएजी उत्पत्ति मॉडल
|
||||
|
||||
```
|
||||
Question (urn:trustgraph:docrag:{uuid})
|
||||
│
|
||||
│ tg:query = "User's question"
|
||||
│ prov:startedAtTime = timestamp
|
||||
│ rdf:type = prov:Activity, tg:Question
|
||||
│
|
||||
↓ prov:wasGeneratedBy
|
||||
│
|
||||
Exploration (urn:trustgraph:docrag:{uuid}/exploration)
|
||||
│
|
||||
│ tg:chunkCount = 5
|
||||
│ tg:selectedChunk = "chunk-id-1"
|
||||
│ tg:selectedChunk = "chunk-id-2"
|
||||
│ ...
|
||||
│ rdf:type = prov:Entity, tg:Exploration
|
||||
│
|
||||
↓ prov:wasDerivedFrom
|
||||
│
|
||||
Synthesis (urn:trustgraph:docrag:{uuid}/synthesis)
|
||||
│
|
||||
│ tg:content = "The synthesized answer..."
|
||||
│ rdf:type = prov:Entity, tg:Synthesis
|
||||
```
|
||||
|
||||
## आवश्यक परिवर्तन
|
||||
|
||||
### 1. स्कीमा परिवर्तन
|
||||
|
||||
**फ़ाइल:** `trustgraph-base/trustgraph/schema/services/agent.py`
|
||||
|
||||
`AgentRequest` में `session_id` और `collection` फ़ील्ड जोड़ें:
|
||||
```python
|
||||
@dataclass
|
||||
class AgentRequest:
|
||||
question: str = ""
|
||||
state: str = ""
|
||||
group: list[str] | None = None
|
||||
history: list[AgentStep] = field(default_factory=list)
|
||||
user: str = ""
|
||||
collection: str = "default" # NEW: Collection for provenance traces
|
||||
streaming: bool = False
|
||||
session_id: str = "" # NEW: For provenance tracking across iterations
|
||||
```
|
||||
|
||||
**फ़ाइल:** `trustgraph-base/trustgraph/messaging/translators/agent.py`
|
||||
|
||||
अनुवादक को `session_id` और `collection` को `to_pulsar()` और `from_pulsar()` दोनों में संभालने के लिए अपडेट करें।
|
||||
|
||||
### 2. एजेंट सेवा में "एक्सप्लेनेबिलिटी" उत्पादक जोड़ें
|
||||
|
||||
**फ़ाइल:** `trustgraph-flow/trustgraph/agent/react/service.py`
|
||||
|
||||
एक "एक्सप्लेनेबिलिटी" उत्पादक को पंजीकृत करें (ग्राफआरएजी के समान पैटर्न):
|
||||
```python
|
||||
from ... base import ProducerSpec
|
||||
from ... schema import Triples
|
||||
|
||||
# In __init__:
|
||||
self.register_specification(
|
||||
ProducerSpec(
|
||||
name = "explainability",
|
||||
schema = Triples,
|
||||
)
|
||||
)
|
||||
```
|
||||
|
||||
### 3. उत्पत्ति त्रिक निर्माण
|
||||
|
||||
**फ़ाइल:** `trustgraph-base/trustgraph/provenance/agent.py`
|
||||
|
||||
सहायक फ़ंक्शन बनाएँ (ग्राफ़आरएजी के `question_triples`, `exploration_triples`, आदि के समान):
|
||||
```python
|
||||
def agent_session_triples(session_uri, query, timestamp):
|
||||
"""Generate triples for agent Question."""
|
||||
return [
|
||||
Triple(s=session_uri, p=RDF_TYPE, o=PROV_ACTIVITY),
|
||||
Triple(s=session_uri, p=RDF_TYPE, o=TG_QUESTION),
|
||||
Triple(s=session_uri, p=TG_QUERY, o=query),
|
||||
Triple(s=session_uri, p=PROV_STARTED_AT_TIME, o=timestamp),
|
||||
]
|
||||
|
||||
def agent_iteration_triples(iteration_uri, parent_uri, thought, action, arguments, observation):
|
||||
"""Generate triples for one Analysis step."""
|
||||
return [
|
||||
Triple(s=iteration_uri, p=RDF_TYPE, o=PROV_ENTITY),
|
||||
Triple(s=iteration_uri, p=RDF_TYPE, o=TG_ANALYSIS),
|
||||
Triple(s=iteration_uri, p=TG_THOUGHT, o=thought),
|
||||
Triple(s=iteration_uri, p=TG_ACTION, o=action),
|
||||
Triple(s=iteration_uri, p=TG_ARGUMENTS, o=json.dumps(arguments)),
|
||||
Triple(s=iteration_uri, p=TG_OBSERVATION, o=observation),
|
||||
Triple(s=iteration_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
|
||||
]
|
||||
|
||||
def agent_final_triples(final_uri, parent_uri, answer):
|
||||
"""Generate triples for Conclusion."""
|
||||
return [
|
||||
Triple(s=final_uri, p=RDF_TYPE, o=PROV_ENTITY),
|
||||
Triple(s=final_uri, p=RDF_TYPE, o=TG_CONCLUSION),
|
||||
Triple(s=final_uri, p=TG_ANSWER, o=answer),
|
||||
Triple(s=final_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
|
||||
]
|
||||
```
|
||||
|
||||
### 4. प्रकार की परिभाषाएँ
|
||||
|
||||
**फ़ाइल:** `trustgraph-base/trustgraph/provenance/namespaces.py`
|
||||
|
||||
व्याख्यात्मकता इकाई प्रकार और एजेंट विधेयकों को जोड़ें:
|
||||
```python
|
||||
# Explainability entity types (used by both GraphRAG and Agent)
|
||||
TG_QUESTION = TG + "Question"
|
||||
TG_EXPLORATION = TG + "Exploration"
|
||||
TG_FOCUS = TG + "Focus"
|
||||
TG_SYNTHESIS = TG + "Synthesis"
|
||||
TG_ANALYSIS = TG + "Analysis"
|
||||
TG_CONCLUSION = TG + "Conclusion"
|
||||
|
||||
# Agent predicates
|
||||
TG_THOUGHT = TG + "thought"
|
||||
TG_ACTION = TG + "action"
|
||||
TG_ARGUMENTS = TG + "arguments"
|
||||
TG_OBSERVATION = TG + "observation"
|
||||
TG_ANSWER = TG + "answer"
|
||||
```
|
||||
|
||||
## संशोधित फ़ाइलें
|
||||
|
||||
| फ़ाइल | परिवर्तन |
|
||||
|------|--------|
|
||||
| `trustgraph-base/trustgraph/schema/services/agent.py` | AgentRequest में session_id और collection जोड़ें |
|
||||
| `trustgraph-base/trustgraph/messaging/translators/agent.py` | नए फ़ील्ड के लिए ट्रांसलेटर को अपडेट करें |
|
||||
| `trustgraph-base/trustgraph/provenance/namespaces.py` | एंटिटी प्रकार, एजेंट प्रेडिकेट और Document RAG प्रेडिकेट जोड़ें |
|
||||
| `trustgraph-base/trustgraph/provenance/triples.py` | GraphRAG ट्रिपल बिल्डरों में TG प्रकार जोड़ें, Document RAG ट्रिपल बिल्डर जोड़ें |
|
||||
| `trustgraph-base/trustgraph/provenance/uris.py` | Document RAG URI जनरेटर जोड़ें |
|
||||
| `trustgraph-base/trustgraph/provenance/__init__.py` | नए प्रकार, प्रेडिकेट और Document RAG फ़ंक्शन निर्यात करें |
|
||||
| `trustgraph-base/trustgraph/schema/services/retrieval.py` | DocumentRagResponse में explain_id और explain_graph जोड़ें |
|
||||
| `trustgraph-base/trustgraph/messaging/translators/retrieval.py` | व्याख्यात्मक फ़ील्ड के लिए DocumentRagResponseTranslator को अपडेट करें |
|
||||
| `trustgraph-flow/trustgraph/agent/react/service.py` | व्याख्यात्मक उत्पादक + रिकॉर्डिंग लॉजिक जोड़ें |
|
||||
| `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` | व्याख्यात्मक कॉलबैक जोड़ें और प्रोवेनेंस ट्रिपल उत्सर्जित करें |
|
||||
| `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` | व्याख्यात्मक उत्पादक जोड़ें और कॉलबैक को कनेक्ट करें |
|
||||
| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | एजेंट ट्रेस प्रकारों को संभालें |
|
||||
| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | GraphRAG के साथ एजेंट सत्रों को सूचीबद्ध करें |
|
||||
|
||||
## बनाई गई फ़ाइलें
|
||||
|
||||
| फ़ाइल | उद्देश्य |
|
||||
|------|---------|
|
||||
| `trustgraph-base/trustgraph/provenance/agent.py` | एजेंट-विशिष्ट ट्रिपल जनरेटर |
|
||||
|
||||
## CLI अपडेट
|
||||
|
||||
**पहचान:** GraphRAG और Agent Questions दोनों में `tg:Question` प्रकार होता है। निम्नलिखित द्वारा पहचाना जाता है:
|
||||
1. URI पैटर्न: `urn:trustgraph:agent:` बनाम `urn:trustgraph:question:`
|
||||
2. व्युत्पन्न एंटिटीज: `tg:Analysis` (एजेंट) बनाम `tg:Exploration` (GraphRAG)
|
||||
|
||||
**`list_explain_traces.py`:**
|
||||
टाइप कॉलम दिखाता है (एजेंट बनाम GraphRAG)
|
||||
|
||||
**`show_explain_trace.py`:**
|
||||
स्वचालित रूप से ट्रेस प्रकार का पता लगाता है
|
||||
एजेंट रेंडरिंग दिखाता है: प्रश्न → विश्लेषण चरण(s) → निष्कर्ष
|
||||
|
||||
## पिछली अनुकूलता
|
||||
|
||||
`session_id` डिफ़ॉल्ट रूप से `""` होता है - पुराने अनुरोध काम करते हैं, लेकिन उनमें प्रोवेनेंस नहीं होगा
|
||||
`collection` डिफ़ॉल्ट रूप से `"default"` होता है - उचित बैकअप
|
||||
CLI दोनों ट्रेस प्रकारों को आसानी से संभालता है
|
||||
|
||||
## सत्यापन
|
||||
|
||||
```bash
|
||||
# Run an agent query
|
||||
tg-invoke-agent -q "What is the capital of France?"
|
||||
|
||||
# List traces (should show agent sessions with Type column)
|
||||
tg-list-explain-traces -U trustgraph -C default
|
||||
|
||||
# Show agent trace
|
||||
tg-show-explain-trace "urn:trustgraph:agent:xxx"
|
||||
```
|
||||
|
||||
## भविष्य की योजनाएं (इस पुल अनुरोध में नहीं)
|
||||
|
||||
डीएजी निर्भरताएँ (जब विश्लेषण एन, पिछले कई विश्लेषणों के परिणामों का उपयोग करता है)
|
||||
टूल-विशिष्ट उत्पत्ति लिंकिंग (नॉलेजक्वेरी → इसका ग्राफआरएजी ट्रेस)
|
||||
स्ट्रीमिंग उत्पत्ति उत्सर्जन (जैसे-जैसे उत्पन्न होता है, अंत में बैच न करें)
|
||||
113
docs/tech-specs/hi/architecture-principles.hi.md
Normal file
113
docs/tech-specs/hi/architecture-principles.hi.md
Normal file
|
|
@ -0,0 +1,113 @@
|
|||
---
|
||||
layout: default
|
||||
title: "नॉलेज ग्राफ आर्किटेक्चर फाउंडेशन"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# नॉलेज ग्राफ आर्किटेक्चर फाउंडेशन
|
||||
|
||||
> **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.
|
||||
|
||||
## फाउंडेशन 1: सब्जेक्ट-प्रेडिकेट-ऑब्जेक्ट (एसपीओ) ग्राफ मॉडल
|
||||
**निर्णय**: एस.पी.ओ./आर.डी.एफ. को मुख्य नॉलेज रिप्रेजेंटेशन मॉडल के रूप में अपनाएं
|
||||
|
||||
**तर्क**:
|
||||
यह अधिकतम लचीलापन और मौजूदा ग्राफ तकनीकों के साथ इंटरऑपरेबिलिटी प्रदान करता है।
|
||||
यह अन्य ग्राफ क्वेरी भाषाओं (जैसे, एस.पी.ओ. → साइफर, लेकिन इसके विपरीत नहीं) में सहज अनुवाद को सक्षम बनाता है।
|
||||
यह एक ऐसा आधार बनाता है जो "बहुत सारी" डाउनस्ट्रीम क्षमताओं को "अनलॉक" करता है।
|
||||
यह नोड-टू-नोड संबंधों (एस.पी.ओ.) और नोड-टू-लिटरल संबंधों (आर.डी.एफ.) दोनों का समर्थन करता है।
|
||||
|
||||
**कार्यान्वयन**:
|
||||
मुख्य डेटा संरचना: `node → edge → {node | literal}`
|
||||
विस्तारित एस.पी.ओ. ऑपरेशनों का समर्थन करते हुए आर.डी.एफ. मानकों के साथ अनुकूलता बनाए रखें।
|
||||
|
||||
## फाउंडेशन 2: एलएलएम-नेटिव नॉलेज ग्राफ इंटीग्रेशन
|
||||
**निर्णय**: एलएलएम इंटरैक्शन के लिए नॉलेज ग्राफ संरचना और ऑपरेशनों को अनुकूलित करें
|
||||
|
||||
**तर्क**:
|
||||
प्राथमिक उपयोग मामला एलएलएम का नॉलेज ग्राफ के साथ इंटरफेस करना है।
|
||||
ग्राफ तकनीक विकल्पों को अन्य विचारों की तुलना में एलएलएम अनुकूलता को प्राथमिकता देनी चाहिए।
|
||||
यह प्राकृतिक भाषा प्रसंस्करण वर्कफ़्लो को संरचित ज्ञान का लाभ उठाने में सक्षम बनाता है।
|
||||
|
||||
**कार्यान्वयन**:
|
||||
ऐसे ग्राफ स्कीमा डिज़ाइन करें जिन्हें एलएलएम प्रभावी ढंग से तर्क दे सकें।
|
||||
सामान्य एलएलएम इंटरैक्शन पैटर्न के लिए अनुकूलित करें।
|
||||
|
||||
## फाउंडेशन 3: एम्बेडिंग-आधारित ग्राफ नेविगेशन
|
||||
**निर्णय**: प्राकृतिक भाषा प्रश्नों को एम्बेडिंग के माध्यम से ग्राफ नोड्स पर सीधे मैप करें
|
||||
|
||||
**तर्क**:
|
||||
यह एनएलपी क्वेरी से ग्राफ नेविगेशन के लिए सबसे सरल पथ को सक्षम करता है।
|
||||
जटिल मध्यवर्ती क्वेरी पीढ़ी चरणों से बचें।
|
||||
ग्राफ संरचना के भीतर कुशल सिमेंटिक खोज क्षमताओं को प्रदान करता है।
|
||||
|
||||
**कार्यान्वयन**:
|
||||
`NLP Query → Graph Embeddings → Graph Nodes`
|
||||
सभी ग्राफ एंटिटीज के लिए एम्बेडिंग रिप्रेजेंटेशन बनाए रखें।
|
||||
क्वेरी रिज़ॉल्यूशन के लिए प्रत्यक्ष सिमेंटिक समानता मिलान का समर्थन करें।
|
||||
|
||||
## फाउंडेशन 4: डिस्ट्रीब्यूटेड एंटिटी रिज़ॉल्यूशन विद डिटर्मिनिस्टिक आइडेंटिफायर्स
|
||||
**निर्णय**: डिस्ट्रीब्यूटेड एंटिटी आइडेंटिफिकेशन (80% नियम) के साथ समानांतर नॉलेज एक्सट्रैक्शन का समर्थन करें
|
||||
|
||||
**तर्क**:
|
||||
**आदर्श**: पूर्ण राज्य दृश्यता के साथ सिंगल-प्रोसेस एक्सट्रैक्शन सही एंटिटी रिज़ॉल्यूशन को सक्षम करता है।
|
||||
**वास्तविकता**: स्केलेबिलिटी आवश्यकताओं के लिए समानांतर प्रसंस्करण क्षमताओं की आवश्यकता होती है।
|
||||
**समझौता**: वितरित प्रक्रियाओं में नियतात्मक एंटिटी पहचान के लिए डिज़ाइन करें।
|
||||
|
||||
**कार्यान्वयन**:
|
||||
ऐसे तंत्र विकसित करें जो विभिन्न नॉलेज एक्सट्रैक्टर्स में सुसंगत, अद्वितीय पहचानकर्ता उत्पन्न करते हैं।
|
||||
विभिन्न प्रक्रियाओं में उल्लिखित एक ही एंटिटी को समान पहचानकर्ता पर हल किया जाना चाहिए।
|
||||
इस बात को स्वीकार करें कि ~20% एज केस के लिए वैकल्पिक प्रसंस्करण मॉडल की आवश्यकता हो सकती है।
|
||||
जटिल एंटिटी रिज़ॉल्यूशन परिदृश्यों के लिए फॉलबैक तंत्र डिज़ाइन करें।
|
||||
|
||||
## फाउंडेशन 5: इवेंट-ड्रिवन आर्किटेक्चर विद पब्लिश-सब्सक्राइब
|
||||
**निर्णय**: सिस्टम समन्वय के लिए एक पब-सब मैसेजिंग सिस्टम लागू करें
|
||||
|
||||
**तर्क**:
|
||||
यह नॉलेज एक्सट्रैक्शन, स्टोरेज और क्वेरी घटकों के बीच ढीला युग्मन को सक्षम करता है।
|
||||
यह पूरे सिस्टम में रीयल-टाइम अपडेट और नोटिफिकेशन का समर्थन करता है।
|
||||
यह स्केलेबल, वितरित प्रसंस्करण वर्कफ़्लो को सुविधाजनक बनाता है।
|
||||
|
||||
**कार्यान्वयन**:
|
||||
सिस्टम घटकों के बीच मैसेज-ड्रिवन समन्वय।
|
||||
नॉलेज अपडेट, एक्सट्रैक्शन पूरा होने और क्वेरी परिणामों के लिए इवेंट स्ट्रीम।
|
||||
|
||||
## फाउंडेशन 6: रीएंट्रेंट एजेंट कम्युनिकेशन
|
||||
**निर्णय**: एजेंट-आधारित प्रसंस्करण के लिए रीएंट्रेंट पब-सब ऑपरेशंस का समर्थन करें
|
||||
|
||||
**तर्क**:
|
||||
यह परिष्कृत एजेंट वर्कफ़्लो को सक्षम करता है जहां एजेंट एक-दूसरे को ट्रिगर और प्रतिक्रिया कर सकते हैं।
|
||||
यह जटिल, बहु-चरणीय नॉलेज प्रोसेसिंग पाइपलाइनों का समर्थन करता है।
|
||||
यह पुनरावर्ती और पुनरावृत्त प्रसंस्करण पैटर्न की अनुमति देता है।
|
||||
|
||||
**कार्यान्वयन**:
|
||||
पब-सब सिस्टम को सुरक्षित रूप से रीएंट्रेंट कॉल को संभालना चाहिए।
|
||||
एजेंट समन्वय तंत्र जो अनंत लूप को रोकते हैं।
|
||||
एजेंट वर्कफ़्लो ऑर्केस्ट्रेशन के लिए समर्थन।
|
||||
|
||||
## फाउंडेशन 7: कॉलम डेटा स्टोर इंटीग्रेशन
|
||||
**निर्णय**: कॉलम स्टोरेज सिस्टम के साथ क्वेरी अनुकूलता सुनिश्चित करें
|
||||
|
||||
**तर्क**:
|
||||
यह बड़े नॉलेज डेटासेट पर कुशल विश्लेषणात्मक प्रश्नों को सक्षम करता है।
|
||||
यह बिजनेस इंटेलिजेंस और रिपोर्टिंग उपयोग मामलों का समर्थन करता है।
|
||||
यह ग्राफ-आधारित नॉलेज रिप्रेजेंटेशन को पारंपरिक विश्लेषणात्मक वर्कफ़्लो के साथ जोड़ता है।
|
||||
|
||||
**कार्यान्वयन**:
|
||||
क्वेरी ट्रांसलेशन लेयर: ग्राफ क्वेरी → कॉलम क्वेरी
|
||||
एक हाइब्रिड स्टोरेज रणनीति जो ग्राफ ऑपरेशंस और विश्लेषणात्मक वर्कलोड दोनों का समर्थन करती है।
|
||||
दोनों प्रतिमानों में क्वेरी प्रदर्शन बनाए रखें।
|
||||
|
||||
--
|
||||
|
||||
## आर्किटेक्चर प्रिंसिपल्स समरी
|
||||
|
||||
1. **लचीलापन पहले**: एस.पी.ओ./आर.डी.एफ. मॉडल अधिकतम अनुकूलन क्षमता प्रदान करता है।
|
||||
2. **एलएलएम अनुकूलन**: सभी डिज़ाइन निर्णयों पर एलएलएम इंटरैक्शन आवश्यकताओं पर विचार किया जाता है।
|
||||
3. **सिमेंटिक दक्षता**: इष्टतम क्वेरी प्रदर्शन के लिए प्रत्यक्ष एम्बेडिंग-टू-नोड मैपिंग।
|
||||
4. **व्यावहारिक स्केलेबिलिटी**: सही सटीकता को व्यावहारिक वितरित प्रसंस्करण के साथ संतुलित करें।
|
||||
5. **इवेंट-ड्रिवन समन्वय**: पब-सब ढीला युग्मन और स्केलेबिलिटी को सक्षम करता है।
|
||||
6. **एजेंट-फ्रेंडली**: जटिल, बहु-एजेंट प्रसंस्करण वर्कफ़्लो का समर्थन करें।
|
||||
7. **विश्लेषणात्मक अनुकूलता**: व्यापक क्वेरी के लिए ग्राफ और कॉलम प्रतिमानों को जोड़ें।
|
||||
|
||||
ये फाउंडेशन एक नॉलेज ग्राफ आर्किटेक्चर स्थापित करते हैं जो सैद्धांतिक कठोरता को व्यावहारिक स्केलेबिलिटी आवश्यकताओं के साथ संतुलित करता है, जो एलएलएम एकीकरण और वितरित प्रसंस्करण के लिए अनुकूलित है।
|
||||
339
docs/tech-specs/hi/cassandra-consolidation.hi.md
Normal file
339
docs/tech-specs/hi/cassandra-consolidation.hi.md
Normal file
|
|
@ -0,0 +1,339 @@
|
|||
---
|
||||
layout: default
|
||||
title: "तकनीकी विनिर्देश: कैसेंड्रा कॉन्फ़िगरेशन समेकन"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# तकनीकी विनिर्देश: कैसेंड्रा कॉन्फ़िगरेशन समेकन
|
||||
|
||||
> **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.
|
||||
|
||||
**स्थिति:** मसौदा
|
||||
**लेखक:** सहायक
|
||||
**तिथि:** 2024-09-03
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह विनिर्देश ट्रस्टग्राफ कोडबेस में कैसेंड्रा कनेक्शन मापदंडों के लिए असंगत नामकरण और कॉन्फ़िगरेशन पैटर्न को संबोधित करता है। वर्तमान में, दो अलग-अलग पैरामीटर नामकरण योजनाएं मौजूद हैं (`cassandra_*` बनाम `graph_*`), जिससे भ्रम और रखरखाव जटिलता होती है।
|
||||
|
||||
## समस्या विवरण
|
||||
|
||||
कोडबेस वर्तमान में कैसेंड्रा कॉन्फ़िगरेशन मापदंडों के दो अलग-अलग सेट का उपयोग करता है:
|
||||
|
||||
1. **ज्ञान/कॉन्फ़िग/लाइब्रेरी मॉड्यूल** निम्नलिखित का उपयोग करते हैं:
|
||||
`cassandra_host` (होस्ट की सूची)
|
||||
`cassandra_user`
|
||||
`cassandra_password`
|
||||
|
||||
2. **ग्राफ/भंडारण मॉड्यूल** निम्नलिखित का उपयोग करते हैं:
|
||||
`graph_host` (एकल होस्ट, कभी-कभी सूची में परिवर्तित)
|
||||
`graph_username`
|
||||
`graph_password`
|
||||
|
||||
3. **असंगत कमांड-लाइन एक्सपोजर**:
|
||||
कुछ प्रोसेसर (जैसे, `kg-store`) कैसेंड्रा सेटिंग्स को कमांड-लाइन तर्कों के रूप में उजागर नहीं करते हैं
|
||||
अन्य प्रोसेसर उन्हें अलग-अलग नामों और प्रारूपों के साथ उजागर करते हैं
|
||||
सहायता पाठ पर्यावरण चर डिफ़ॉल्ट को प्रतिबिंबित नहीं करता है
|
||||
|
||||
दोनों पैरामीटर सेट एक ही कैसेंड्रा क्लस्टर से जुड़ते हैं, लेकिन अलग-अलग नामकरण सम्मेलनों के साथ, जिससे:
|
||||
उपयोगकर्ताओं के लिए कॉन्फ़िगरेशन भ्रम
|
||||
रखरखाव का बढ़ता बोझ
|
||||
असंगत प्रलेखन
|
||||
गलत कॉन्फ़िगरेशन की संभावना
|
||||
कुछ प्रोसेसर में कमांड-लाइन के माध्यम से सेटिंग्स को ओवरराइड करने में असमर्थता
|
||||
|
||||
## प्रस्तावित समाधान
|
||||
|
||||
### 1. पैरामीटर नामों का मानकीकरण
|
||||
|
||||
सभी मॉड्यूल सुसंगत `cassandra_*` पैरामीटर नामों का उपयोग करेंगे:
|
||||
`cassandra_host` - होस्ट की सूची (आंतरिक रूप से सूची के रूप में संग्रहीत)
|
||||
`cassandra_username` - प्रमाणीकरण के लिए उपयोगकर्ता नाम
|
||||
`cassandra_password` - प्रमाणीकरण के लिए पासवर्ड
|
||||
|
||||
### 2. कमांड-लाइन तर्क
|
||||
|
||||
सभी प्रोसेसर को कैसेंड्रा कॉन्फ़िगरेशन को कमांड-लाइन तर्कों के माध्यम से उजागर करना होगा:
|
||||
`--cassandra-host` - होस्ट की अल्पविराम-विभाजित सूची
|
||||
`--cassandra-username` - प्रमाणीकरण के लिए उपयोगकर्ता नाम
|
||||
`--cassandra-password` - प्रमाणीकरण के लिए पासवर्ड
|
||||
|
||||
### 3. पर्यावरण चर बैकअप
|
||||
|
||||
यदि कमांड-लाइन पैरामीटर स्पष्ट रूप से प्रदान नहीं किए जाते हैं, तो सिस्टम पर्यावरण चर की जांच करेगा:
|
||||
`CASSANDRA_HOST` - होस्ट की अल्पविराम-विभाजित सूची
|
||||
`CASSANDRA_USERNAME` - प्रमाणीकरण के लिए उपयोगकर्ता नाम
|
||||
`CASSANDRA_PASSWORD` - प्रमाणीकरण के लिए पासवर्ड
|
||||
|
||||
### 4. डिफ़ॉल्ट मान
|
||||
|
||||
यदि न तो कमांड-लाइन पैरामीटर और न ही पर्यावरण चर निर्दिष्ट हैं:
|
||||
`cassandra_host` डिफ़ॉल्ट रूप से `["cassandra"]` है
|
||||
`cassandra_username` डिफ़ॉल्ट रूप से `None` है (कोई प्रमाणीकरण नहीं)
|
||||
`cassandra_password` डिफ़ॉल्ट रूप से `None` है (कोई प्रमाणीकरण नहीं)
|
||||
|
||||
### 5. सहायता पाठ आवश्यकताएँ
|
||||
|
||||
`--help` आउटपुट को:
|
||||
जब सेट किया गया हो तो पर्यावरण चर मानों को डिफ़ॉल्ट के रूप में दिखाना चाहिए
|
||||
पासवर्ड मानों को कभी भी प्रदर्शित नहीं करना चाहिए (इसके बजाय `****` या `<set>` दिखाएं)
|
||||
सहायता पाठ में समाधान क्रम को स्पष्ट रूप से इंगित करना चाहिए
|
||||
|
||||
उदाहरण सहायता आउटपुट:
|
||||
```
|
||||
--cassandra-host HOST
|
||||
Cassandra host list, comma-separated (default: prod-cluster-1,prod-cluster-2)
|
||||
[from CASSANDRA_HOST environment variable]
|
||||
|
||||
--cassandra-username USERNAME
|
||||
Cassandra username (default: cassandra_user)
|
||||
[from CASSANDRA_USERNAME environment variable]
|
||||
|
||||
--cassandra-password PASSWORD
|
||||
Cassandra password (default: <set from environment>)
|
||||
```
|
||||
|
||||
## कार्यान्वयन विवरण
|
||||
|
||||
### पैरामीटर समाधान का क्रम
|
||||
|
||||
प्रत्येक कैसेंड्रा पैरामीटर के लिए, समाधान का क्रम इस प्रकार होगा:
|
||||
1. कमांड-लाइन तर्क मान
|
||||
2. पर्यावरण चर (`CASSANDRA_*`)
|
||||
3. डिफ़ॉल्ट मान
|
||||
|
||||
### होस्ट पैरामीटर हैंडलिंग
|
||||
|
||||
`cassandra_host` पैरामीटर:
|
||||
कमांड-लाइन अल्पविराम-विभाजित स्ट्रिंग स्वीकार करता है: `--cassandra-host "host1,host2,host3"`
|
||||
पर्यावरण चर अल्पविराम-विभाजित स्ट्रिंग स्वीकार करता है: `CASSANDRA_HOST="host1,host2,host3"`
|
||||
आंतरिक रूप से हमेशा सूची के रूप में संग्रहीत किया जाता है: `["host1", "host2", "host3"]`
|
||||
एकल होस्ट: `"localhost"` → `["localhost"]` में परिवर्तित
|
||||
पहले से ही एक सूची: `["host1", "host2"]` → जैसा है उपयोग किया जाता है
|
||||
|
||||
### प्रमाणीकरण तर्क
|
||||
|
||||
प्रमाणीकरण का उपयोग तब किया जाएगा जब `cassandra_username` और `cassandra_password` दोनों प्रदान किए जाते हैं:
|
||||
```python
|
||||
if cassandra_username and cassandra_password:
|
||||
# Use SSL context and PlainTextAuthProvider
|
||||
else:
|
||||
# Connect without authentication
|
||||
```
|
||||
|
||||
## संशोधित करने योग्य फ़ाइलें
|
||||
|
||||
### `graph_*` पैरामीटर का उपयोग करने वाले मॉड्यूल (जिन्हें बदला जाना है):
|
||||
`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/objects/cassandra/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/rows/cassandra/write.py`
|
||||
`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
|
||||
|
||||
### `cassandra_*` पैरामीटर का उपयोग करने वाले मॉड्यूल (जिन्हें पर्यावरण बैकअप के साथ अपडेट किया जाना है):
|
||||
`trustgraph-flow/trustgraph/tables/config.py`
|
||||
`trustgraph-flow/trustgraph/tables/knowledge.py`
|
||||
`trustgraph-flow/trustgraph/tables/library.py`
|
||||
`trustgraph-flow/trustgraph/storage/knowledge/store.py`
|
||||
`trustgraph-flow/trustgraph/cores/knowledge.py`
|
||||
`trustgraph-flow/trustgraph/librarian/librarian.py`
|
||||
`trustgraph-flow/trustgraph/librarian/service.py`
|
||||
`trustgraph-flow/trustgraph/config/service/service.py`
|
||||
`trustgraph-flow/trustgraph/cores/service.py`
|
||||
|
||||
### अपडेट करने योग्य परीक्षण फ़ाइलें:
|
||||
`tests/unit/test_cores/test_knowledge_manager.py`
|
||||
`tests/unit/test_storage/test_triples_cassandra_storage.py`
|
||||
`tests/unit/test_query/test_triples_cassandra_query.py`
|
||||
`tests/integration/test_objects_cassandra_integration.py`
|
||||
|
||||
## कार्यान्वयन रणनीति
|
||||
|
||||
### चरण 1: सामान्य कॉन्फ़िगरेशन हेल्पर बनाएं
|
||||
सभी प्रोसेसरों में कैसेंड्रा कॉन्फ़िगरेशन को मानकीकृत करने के लिए उपयोगिता फ़ंक्शन बनाएं:
|
||||
|
||||
```python
|
||||
import os
|
||||
import argparse
|
||||
|
||||
def get_cassandra_defaults():
|
||||
"""Get default values from environment variables or fallback."""
|
||||
return {
|
||||
'host': os.getenv('CASSANDRA_HOST', 'cassandra'),
|
||||
'username': os.getenv('CASSANDRA_USERNAME'),
|
||||
'password': os.getenv('CASSANDRA_PASSWORD')
|
||||
}
|
||||
|
||||
def add_cassandra_args(parser: argparse.ArgumentParser):
|
||||
"""
|
||||
Add standardized Cassandra arguments to an argument parser.
|
||||
Shows environment variable values in help text.
|
||||
"""
|
||||
defaults = get_cassandra_defaults()
|
||||
|
||||
# Format help text with env var indication
|
||||
host_help = f"Cassandra host list, comma-separated (default: {defaults['host']})"
|
||||
if 'CASSANDRA_HOST' in os.environ:
|
||||
host_help += " [from CASSANDRA_HOST]"
|
||||
|
||||
username_help = f"Cassandra username"
|
||||
if defaults['username']:
|
||||
username_help += f" (default: {defaults['username']})"
|
||||
if 'CASSANDRA_USERNAME' in os.environ:
|
||||
username_help += " [from CASSANDRA_USERNAME]"
|
||||
|
||||
password_help = "Cassandra password"
|
||||
if defaults['password']:
|
||||
password_help += " (default: <set>)"
|
||||
if 'CASSANDRA_PASSWORD' in os.environ:
|
||||
password_help += " [from CASSANDRA_PASSWORD]"
|
||||
|
||||
parser.add_argument(
|
||||
'--cassandra-host',
|
||||
default=defaults['host'],
|
||||
help=host_help
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--cassandra-username',
|
||||
default=defaults['username'],
|
||||
help=username_help
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--cassandra-password',
|
||||
default=defaults['password'],
|
||||
help=password_help
|
||||
)
|
||||
|
||||
def resolve_cassandra_config(args) -> tuple[list[str], str|None, str|None]:
|
||||
"""
|
||||
Convert argparse args to Cassandra configuration.
|
||||
|
||||
Returns:
|
||||
tuple: (hosts_list, username, password)
|
||||
"""
|
||||
# Convert host string to list
|
||||
if isinstance(args.cassandra_host, str):
|
||||
hosts = [h.strip() for h in args.cassandra_host.split(',')]
|
||||
else:
|
||||
hosts = args.cassandra_host
|
||||
|
||||
return hosts, args.cassandra_username, args.cassandra_password
|
||||
```
|
||||
|
||||
### चरण 2: `graph_*` पैरामीटर का उपयोग करके मॉड्यूल को अपडेट करें
|
||||
1. पैरामीटर नामों को `graph_*` से `cassandra_*` में बदलें
|
||||
2. कस्टम `add_args()` विधियों को मानकीकृत `add_cassandra_args()` से बदलें
|
||||
3. सामान्य कॉन्फ़िगरेशन सहायक फ़ंक्शन का उपयोग करें
|
||||
4. दस्तावेज़ स्ट्रिंग को अपडेट करें
|
||||
|
||||
उदाहरण परिवर्तन:
|
||||
```python
|
||||
# OLD CODE
|
||||
@staticmethod
|
||||
def add_args(parser):
|
||||
parser.add_argument(
|
||||
'-g', '--graph-host',
|
||||
default="localhost",
|
||||
help=f'Graph host (default: localhost)'
|
||||
)
|
||||
parser.add_argument(
|
||||
'--graph-username',
|
||||
default=None,
|
||||
help=f'Cassandra username'
|
||||
)
|
||||
|
||||
# NEW CODE
|
||||
@staticmethod
|
||||
def add_args(parser):
|
||||
FlowProcessor.add_args(parser)
|
||||
add_cassandra_args(parser) # Use standard helper
|
||||
```
|
||||
|
||||
### चरण 3: `cassandra_*` पैरामीटर का उपयोग करके मॉड्यूल को अपडेट करें
|
||||
1. उन स्थानों पर कमांड-लाइन तर्क समर्थन जोड़ें जहां यह गायब है (उदाहरण के लिए, `kg-store`)
|
||||
2. मौजूदा तर्क परिभाषाओं को `add_cassandra_args()` से बदलें
|
||||
3. सुसंगत समाधान के लिए `resolve_cassandra_config()` का उपयोग करें
|
||||
4. सुसंगत होस्ट सूची प्रबंधन सुनिश्चित करें
|
||||
|
||||
### चरण 4: परीक्षण और दस्तावेज़ को अपडेट करें
|
||||
1. सभी परीक्षण फ़ाइलों को नए पैरामीटर नामों का उपयोग करने के लिए अपडेट करें
|
||||
2. CLI दस्तावेज़ को अपडेट करें
|
||||
3. API दस्तावेज़ को अपडेट करें
|
||||
4. पर्यावरण चर दस्तावेज़ जोड़ें
|
||||
|
||||
## पिछली अनुकूलता
|
||||
|
||||
संक्रमण के दौरान पिछली अनुकूलता बनाए रखने के लिए:
|
||||
|
||||
1. `graph_*` पैरामीटर के लिए **अवरोधन चेतावनी**
|
||||
2. **पैरामीटर उपनाम** - शुरू में पुराने और नए दोनों नामों को स्वीकार करें
|
||||
3. कई रिलीज़ में **चरणबद्ध कार्यान्वयन**
|
||||
4. माइग्रेशन गाइड के साथ **दस्तावेज़ अपडेट**
|
||||
|
||||
पिछली अनुकूलता कोड का उदाहरण:
|
||||
```python
|
||||
def __init__(self, **params):
|
||||
# Handle deprecated graph_* parameters
|
||||
if 'graph_host' in params:
|
||||
warnings.warn("graph_host is deprecated, use cassandra_host", DeprecationWarning)
|
||||
params.setdefault('cassandra_host', params.pop('graph_host'))
|
||||
|
||||
if 'graph_username' in params:
|
||||
warnings.warn("graph_username is deprecated, use cassandra_username", DeprecationWarning)
|
||||
params.setdefault('cassandra_username', params.pop('graph_username'))
|
||||
|
||||
# ... continue with standard resolution
|
||||
```
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
1. **यूनिट परीक्षण** कॉन्फ़िगरेशन रिज़ॉल्यूशन लॉजिक के लिए
|
||||
2. विभिन्न कॉन्फ़िगरेशन संयोजनों के साथ **एकीकरण परीक्षण**
|
||||
3. **पर्यावरण चर परीक्षण**
|
||||
4. **पिछड़ा संगतता परीक्षण** अप्रचलित मापदंडों के साथ
|
||||
5. **डॉकर कंपोज़ परीक्षण** पर्यावरण चर के साथ
|
||||
|
||||
## दस्तावेज़ अपडेट
|
||||
|
||||
1. सभी CLI कमांड दस्तावेज़ों को अपडेट करें
|
||||
2. API दस्तावेज़ों को अपडेट करें
|
||||
3. माइग्रेशन गाइड बनाएं
|
||||
4. डॉकर कंपोज़ उदाहरणों को अपडेट करें
|
||||
5. कॉन्फ़िगरेशन संदर्भ दस्तावेज़ को अपडेट करें
|
||||
|
||||
## जोखिम और निवारण
|
||||
|
||||
| जोखिम | प्रभाव | निवारण |
|
||||
|------|--------|------------|
|
||||
| उपयोगकर्ताओं के लिए ब्रेकिंग परिवर्तन | उच्च | पिछड़े संगतता अवधि लागू करें |
|
||||
| संक्रमण के दौरान कॉन्फ़िगरेशन भ्रम | मध्यम | स्पष्ट दस्तावेज़ और अवमूल्यन चेतावनियाँ |
|
||||
| परीक्षण विफलताएँ | मध्यम | व्यापक परीक्षण अपडेट |
|
||||
| डॉकर परिनियोजन मुद्दे | उच्च | सभी डॉकर कंपोज़ उदाहरणों को अपडेट करें |
|
||||
|
||||
## सफलता मानदंड
|
||||
|
||||
[ ] सभी मॉड्यूल सुसंगत `cassandra_*` पैरामीटर नामों का उपयोग करते हैं
|
||||
[ ] सभी प्रोसेसर कमांड-लाइन तर्कों के माध्यम से कैसेंड्रा सेटिंग्स को उजागर करते हैं
|
||||
[ ] कमांड-लाइन सहायता पाठ पर्यावरण चर डिफ़ॉल्ट दिखाता है
|
||||
[ ] पासवर्ड मान कभी भी सहायता पाठ में प्रदर्शित नहीं होते हैं
|
||||
[ ] पर्यावरण चर बैकअप सही ढंग से काम करता है
|
||||
[ ] `cassandra_host` को आंतरिक रूप से लगातार एक सूची के रूप में संभाला जाता है
|
||||
[ ] कम से कम 2 रिलीज़ के लिए पिछड़े संगतता बनाए रखी जाती है
|
||||
[ ] सभी परीक्षण नए कॉन्फ़िगरेशन सिस्टम के साथ पास होते हैं
|
||||
[ ] दस्तावेज़ पूरी तरह से अपडेट किया गया है
|
||||
[ ] डॉकर कंपोज़ उदाहरण पर्यावरण चर के साथ काम करते हैं
|
||||
|
||||
## समयरेखा
|
||||
|
||||
**सप्ताह 1:** सामान्य कॉन्फ़िगरेशन हेल्पर लागू करें और `graph_*` मॉड्यूल को अपडेट करें
|
||||
**सप्ताह 2:** मौजूदा `cassandra_*` मॉड्यूल में पर्यावरण चर समर्थन जोड़ें
|
||||
**सप्ताह 3:** परीक्षण और दस्तावेज़ अपडेट करें
|
||||
**सप्ताह 4:** एकीकरण परीक्षण और बग फिक्स
|
||||
|
||||
## भविष्य के विचार
|
||||
|
||||
अन्य डेटाबेस कॉन्फ़िगरेशन (जैसे, Elasticsearch) के लिए इस पैटर्न को विस्तारित करने पर विचार करें
|
||||
कॉन्फ़िगरेशन सत्यापन और बेहतर त्रुटि संदेश लागू करें
|
||||
कैसेंड्रा कनेक्शन पूलिंग कॉन्फ़िगरेशन के लिए समर्थन जोड़ें
|
||||
कॉन्फ़िगरेशन फ़ाइल समर्थन (.env फ़ाइलें) जोड़ने पर विचार करें
|
||||
687
docs/tech-specs/hi/cassandra-performance-refactor.hi.md
Normal file
687
docs/tech-specs/hi/cassandra-performance-refactor.hi.md
Normal file
|
|
@ -0,0 +1,687 @@
|
|||
---
|
||||
layout: default
|
||||
title: "तकनीकी विनिर्देश: कैसेंड्रा नॉलेज बेस प्रदर्शन पुनर्निर्माण"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# तकनीकी विनिर्देश: कैसेंड्रा नॉलेज बेस प्रदर्शन पुनर्निर्माण
|
||||
|
||||
> **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.
|
||||
|
||||
**स्थिति:** मसौदा
|
||||
**लेखक:** सहायक
|
||||
**तिथि:** 2025-09-18
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह विनिर्देश ट्रस्टग्राफ कैसेंड्रा नॉलेज बेस कार्यान्वयन में प्रदर्शन संबंधी मुद्दों को संबोधित करता है और आरडीएफ ट्रिपल भंडारण और क्वेरी के लिए अनुकूलन प्रस्तावित करता है।
|
||||
|
||||
## वर्तमान कार्यान्वयन
|
||||
|
||||
### स्कीमा डिज़ाइन
|
||||
|
||||
वर्तमान कार्यान्वयन `trustgraph-flow/trustgraph/direct/cassandra_kg.py` में एक एकल तालिका डिज़ाइन का उपयोग करता है:
|
||||
|
||||
```sql
|
||||
CREATE TABLE triples (
|
||||
collection text,
|
||||
s text,
|
||||
p text,
|
||||
o text,
|
||||
PRIMARY KEY (collection, s, p, o)
|
||||
);
|
||||
```
|
||||
|
||||
**माध्यमिक अनुक्रमणिकाएँ:**
|
||||
`triples_s` ON `s` (विषय)
|
||||
`triples_p` ON `p` (क्रिया)
|
||||
`triples_o` ON `o` (वस्तु)
|
||||
|
||||
### क्वेरी पैटर्न
|
||||
|
||||
वर्तमान कार्यान्वयन 8 अलग-अलग क्वेरी पैटर्न का समर्थन करता है:
|
||||
|
||||
1. **get_all(संग्रह, सीमा=50)** - एक संग्रह के लिए सभी त्रिगुट प्राप्त करें
|
||||
```sql
|
||||
SELECT s, p, o FROM triples WHERE collection = ? LIMIT 50
|
||||
```
|
||||
|
||||
2. **get_s(संग्रह, s, सीमा=10)** - विषय द्वारा खोज।
|
||||
```sql
|
||||
SELECT p, o FROM triples WHERE collection = ? AND s = ? LIMIT 10
|
||||
```
|
||||
|
||||
3. **get_p(संग्रह, p, सीमा=10)** - विधेय द्वारा खोज
|
||||
```sql
|
||||
SELECT s, o FROM triples WHERE collection = ? AND p = ? LIMIT 10
|
||||
```
|
||||
|
||||
4. **get_o(संग्रह, o, सीमा=10)** - ऑब्जेक्ट द्वारा क्वेरी करें।
|
||||
```sql
|
||||
SELECT s, p FROM triples WHERE collection = ? AND o = ? LIMIT 10
|
||||
```
|
||||
|
||||
5. **get_sp(संग्रह, s, p, सीमा=10)** - विषय + विधेय द्वारा खोज।
|
||||
```sql
|
||||
SELECT o FROM triples WHERE collection = ? AND s = ? AND p = ? LIMIT 10
|
||||
```
|
||||
|
||||
6. **get_po(collection, p, o, limit=10)** - पूर्व निर्धारित शर्तों और वस्तुओं के आधार पर खोज ⚠️
|
||||
```sql
|
||||
SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
|
||||
```
|
||||
|
||||
7. **get_os(संग्रह, o, s, सीमा=10)** - ऑब्जेक्ट + विषय द्वारा क्वेरी ⚠️
|
||||
```sql
|
||||
SELECT p FROM triples WHERE collection = ? AND o = ? AND s = ? LIMIT 10 ALLOW FILTERING
|
||||
```
|
||||
|
||||
8. **get_spo(संग्रह, s, p, o, सीमा=10)** - सटीक त्रिगुट मिलान
|
||||
```sql
|
||||
SELECT s as x FROM triples WHERE collection = ? AND s = ? AND p = ? AND o = ? LIMIT 10
|
||||
```
|
||||
|
||||
### वर्तमान आर्किटेक्चर
|
||||
|
||||
**फ़ाइल: `trustgraph-flow/trustgraph/direct/cassandra_kg.py`**
|
||||
सभी कार्यों को संभालने वाली एकल `KnowledgeGraph` क्लास
|
||||
वैश्विक `_active_clusters` सूची के माध्यम से कनेक्शन पूलिंग
|
||||
निश्चित टेबल नाम: `"triples"`
|
||||
प्रति उपयोगकर्ता मॉडल के लिए कीस्पेस
|
||||
फैक्टर 1 के साथ सिंपलस्ट्रैटेजी प्रतिकृति
|
||||
|
||||
**एकीकरण बिंदु:**
|
||||
**राइट पाथ:** `trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
|
||||
**क्वेरी पाथ:** `trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
|
||||
**नॉलेज स्टोर:** `trustgraph-flow/trustgraph/tables/knowledge.py`
|
||||
|
||||
## पहचाने गए प्रदर्शन संबंधी मुद्दे
|
||||
|
||||
### स्कीमा-स्तरीय मुद्दे
|
||||
|
||||
1. **अकुशल प्राइमरी की डिज़ाइन**
|
||||
वर्तमान: `PRIMARY KEY (collection, s, p, o)`
|
||||
सामान्य एक्सेस पैटर्न के लिए खराब क्लस्टरिंग का कारण बनता है
|
||||
महंगे सेकेंडरी इंडेक्स के उपयोग को मजबूर करता है
|
||||
|
||||
2. **सेकेंडरी इंडेक्स का अत्यधिक उपयोग** ⚠️
|
||||
उच्च कार्डिनलिटी कॉलम (s, p, o) पर तीन सेकेंडरी इंडेक्स
|
||||
कैसेंड्रा में सेकेंडरी इंडेक्स महंगे होते हैं और अच्छी तरह से स्केल नहीं होते हैं
|
||||
क्वेरी 6 और 7 को `ALLOW FILTERING` की आवश्यकता होती है, जो खराब डेटा मॉडलिंग का संकेत देती है
|
||||
|
||||
3. **हॉट पार्टिशन का जोखिम**
|
||||
एकल पार्टीशन कुंजी `collection` हॉट पार्टिशन बना सकती है
|
||||
बड़े संग्रह एकल नोड्स पर केंद्रित होंगे
|
||||
लोड बैलेंसिंग के लिए कोई वितरण रणनीति नहीं
|
||||
|
||||
### क्वेरी-स्तरीय मुद्दे
|
||||
|
||||
1. **ALLOW FILTERING का उपयोग** ⚠️
|
||||
दो क्वेरी प्रकार (get_po, get_os) को `ALLOW FILTERING` की आवश्यकता होती है
|
||||
ये क्वेरी कई पार्टिशन को स्कैन करती हैं और बेहद महंगी हैं
|
||||
डेटा के आकार के साथ प्रदर्शन रैखिक रूप से खराब होता है
|
||||
|
||||
2. **अकुशल एक्सेस पैटर्न**
|
||||
सामान्य आरडीएफ क्वेरी पैटर्न के लिए कोई अनुकूलन नहीं
|
||||
बार-बार उपयोग किए जाने वाले क्वेरी संयोजनों के लिए कोई कंपाउंड इंडेक्स नहीं
|
||||
ग्राफ ट्रैवर्सल पैटर्न पर कोई विचार नहीं
|
||||
|
||||
3. **क्वेरी अनुकूलन की कमी**
|
||||
कोई तैयार स्टेटमेंट कैशिंग नहीं
|
||||
कोई क्वेरी संकेत या अनुकूलन रणनीतियाँ नहीं
|
||||
साधारण LIMIT से परे पेजिंग पर कोई विचार नहीं
|
||||
|
||||
## समस्या विवरण
|
||||
|
||||
वर्तमान कैसेंड्रा नॉलेज बेस कार्यान्वयन में दो महत्वपूर्ण प्रदर्शन संबंधी बाधाएं हैं:
|
||||
|
||||
### 1. अकुशल get_po क्वेरी प्रदर्शन
|
||||
|
||||
`get_po(collection, p, o)` क्वेरी `ALLOW FILTERING` की आवश्यकता के कारण बेहद अकुशल है:
|
||||
|
||||
```sql
|
||||
SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
|
||||
```
|
||||
|
||||
**यह समस्याग्रस्त क्यों है:**
|
||||
`ALLOW FILTERING` कैसेंड्रा को संग्रह के भीतर सभी विभाजन को स्कैन करने के लिए मजबूर करता है।
|
||||
डेटा के आकार के साथ प्रदर्शन रैखिक रूप से घटता है।
|
||||
यह एक सामान्य आरडीएफ क्वेरी पैटर्न है (उन विषयों को खोजना जिनके पास एक विशिष्ट विधेय-वस्तु संबंध है)।
|
||||
जैसे-जैसे डेटा बढ़ता है, यह क्लस्टर पर महत्वपूर्ण भार डालता है।
|
||||
|
||||
### 2. खराब क्लस्टरिंग रणनीति
|
||||
|
||||
वर्तमान प्राथमिक कुंजी `PRIMARY KEY (collection, s, p, o)` न्यूनतम क्लस्टरिंग लाभ प्रदान करती है:
|
||||
|
||||
**वर्तमान क्लस्टरिंग के साथ समस्याएं:**
|
||||
विभाजन कुंजी के रूप में `collection` डेटा को प्रभावी ढंग से वितरित नहीं करता है।
|
||||
अधिकांश संग्रहों में विविध डेटा होता है, जिससे क्लस्टरिंग अप्रभावी हो जाती है।
|
||||
आरडीएफ प्रश्नों में सामान्य एक्सेस पैटर्न पर कोई विचार नहीं किया गया है।
|
||||
बड़े संग्रह एकल नोड्स पर "हॉट" विभाजन बनाते हैं।
|
||||
क्लस्टरिंग कॉलम (s, p, o) विशिष्ट ग्राफ ट्रैवर्सल पैटर्न के लिए अनुकूलित नहीं हैं।
|
||||
|
||||
**प्रभाव:**
|
||||
क्वेरी डेटा स्थानीयता से लाभान्वित नहीं होती हैं।
|
||||
खराब कैश उपयोग।
|
||||
क्लस्टर नोड्स में असमान लोड वितरण।
|
||||
जैसे-जैसे संग्रह बढ़ते हैं, स्केलेबिलिटी बाधाएं।
|
||||
|
||||
## प्रस्तावित समाधान: 4-टेबल डीनॉर्मलाइज़ेशन रणनीति
|
||||
|
||||
### अवलोकन
|
||||
|
||||
एकल `triples` तालिका को चार उद्देश्य-निर्मित तालिकाओं से बदलें, प्रत्येक विशिष्ट क्वेरी पैटर्न के लिए अनुकूलित है। यह द्वितीयक अनुक्रमणिकाओं और ALLOW FILTERING की आवश्यकता को समाप्त करता है, जबकि सभी प्रकार की क्वेरी के लिए इष्टतम प्रदर्शन प्रदान करता है। चौथी तालिका समग्र विभाजन कुंजियों के बावजूद कुशल संग्रह हटाने को सक्षम बनाती है।
|
||||
|
||||
### नया स्कीमा डिज़ाइन
|
||||
|
||||
**टेबल 1: विषय-केंद्रित क्वेरी (triples_s)**
|
||||
```sql
|
||||
CREATE TABLE triples_s (
|
||||
collection text,
|
||||
s text,
|
||||
p text,
|
||||
o text,
|
||||
PRIMARY KEY ((collection, s), p, o)
|
||||
);
|
||||
```
|
||||
**अनुकूलन:** get_s, get_sp, get_os
|
||||
**विभाजन कुंजी:** (संग्रह, s) - केवल संग्रह की तुलना में बेहतर वितरण
|
||||
**समूहीकरण:** (p, o) - विषय के लिए कुशल विधेय/वस्तु लुकअप को सक्षम करता है
|
||||
|
||||
**तालिका 2: विधेय-वस्तु प्रश्न (triples_p)**
|
||||
```sql
|
||||
CREATE TABLE triples_p (
|
||||
collection text,
|
||||
p text,
|
||||
o text,
|
||||
s text,
|
||||
PRIMARY KEY ((collection, p), o, s)
|
||||
);
|
||||
```
|
||||
**अनुकूलन:** get_p, get_po (ALLOW FILTERING को हटाता है!)
|
||||
**पार्टिशन कुंजी:** (संग्रह, p) - विधेय द्वारा प्रत्यक्ष पहुंच
|
||||
**क्लस्टरिंग:** (o, s) - कुशल ऑब्जेक्ट-विषय ट्रैवर्सल
|
||||
|
||||
**तालिका 3: ऑब्जेक्ट-केंद्रित प्रश्न (triples_o)**
|
||||
```sql
|
||||
CREATE TABLE triples_o (
|
||||
collection text,
|
||||
o text,
|
||||
s text,
|
||||
p text,
|
||||
PRIMARY KEY ((collection, o), s, p)
|
||||
);
|
||||
```
|
||||
**अनुकूलन:** get_o
|
||||
**विभाजन कुंजी:** (संग्रह, o) - वस्तु द्वारा प्रत्यक्ष पहुंच
|
||||
**समूहीकरण:** (s, p) - कुशल विषय-क्रियापद ट्रैवर्सल
|
||||
|
||||
**तालिका 4: संग्रह प्रबंधन और एस.पी.ओ. प्रश्न (triples_collection)**
|
||||
```sql
|
||||
CREATE TABLE triples_collection (
|
||||
collection text,
|
||||
s text,
|
||||
p text,
|
||||
o text,
|
||||
PRIMARY KEY (collection, s, p, o)
|
||||
);
|
||||
```
|
||||
**अनुकूलन:** get_spo, delete_collection
|
||||
**विभाजन कुंजी:** केवल संग्रह - कुशल संग्रह-स्तरीय संचालन को सक्षम करता है
|
||||
**समूहीकरण:** (s, p, o) - मानक त्रिगुट क्रम
|
||||
**उद्देश्य:** सटीक SPO लुकअप के लिए दोहरे उपयोग और एक हटाने अनुक्रमणिका के रूप में
|
||||
|
||||
### क्वेरी मैपिंग
|
||||
|
||||
| मूल क्वेरी | लक्ष्य तालिका | प्रदर्शन सुधार |
|
||||
|----------------|-------------|------------------------|
|
||||
| get_all(संग्रह) | triples_s | ALLOW FILTERING (स्कैन के लिए स्वीकार्य) |
|
||||
| get_s(संग्रह, s) | triples_s | प्रत्यक्ष विभाजन पहुंच |
|
||||
| get_p(संग्रह, p) | triples_p | प्रत्यक्ष विभाजन पहुंच |
|
||||
| get_o(संग्रह, o) | triples_o | प्रत्यक्ष विभाजन पहुंच |
|
||||
| get_sp(संग्रह, s, p) | triples_s | विभाजन + समूहीकरण |
|
||||
| get_po(संग्रह, p, o) | triples_p | **अब ALLOW FILTERING नहीं!** |
|
||||
| get_os(संग्रह, o, s) | triples_o | विभाजन + समूहीकरण |
|
||||
| get_spo(संग्रह, s, p, o) | triples_collection | सटीक कुंजी लुकअप |
|
||||
| delete_collection(संग्रह) | triples_collection | अनुक्रमणिका पढ़ें, सभी को बैच में हटाएं |
|
||||
|
||||
### संग्रह हटाने की रणनीति
|
||||
|
||||
संयुक्त विभाजन कुंजियों के साथ, हम सीधे `DELETE FROM table WHERE collection = ?` निष्पादित नहीं कर सकते। इसके बजाय:
|
||||
|
||||
1. **पढ़ने का चरण:** सभी त्रिगुटों को सूचीबद्ध करने के लिए `triples_collection` क्वेरी करें:
|
||||
```sql
|
||||
SELECT s, p, o FROM triples_collection WHERE collection = ?
|
||||
```
|
||||
यह कुशल है क्योंकि `collection` इस तालिका के लिए विभाजन कुंजी है।
|
||||
|
||||
2. **हटाने का चरण:** प्रत्येक ट्रिपल (s, p, o) के लिए, सभी 4 तालिकाओं से पूर्ण विभाजन कुंजियों का उपयोग करके हटाएं:
|
||||
```sql
|
||||
DELETE FROM triples_s WHERE collection = ? AND s = ? AND p = ? AND o = ?
|
||||
DELETE FROM triples_p WHERE collection = ? AND p = ? AND o = ? AND s = ?
|
||||
DELETE FROM triples_o WHERE collection = ? AND o = ? AND s = ? AND p = ?
|
||||
DELETE FROM triples_collection WHERE collection = ? AND s = ? AND p = ? AND o = ?
|
||||
```
|
||||
दक्षता के लिए 100 के समूहों में समूहीकृत किया गया।
|
||||
|
||||
**ट्रेड-ऑफ विश्लेषण:**
|
||||
✅ वितरित विभाजनों के साथ इष्टतम क्वेरी प्रदर्शन बनाए रखता है।
|
||||
✅ बड़े संग्रहों के लिए कोई "हॉट" विभाजन नहीं।
|
||||
❌ अधिक जटिल हटाने का तर्क (पढ़ें-फिर-हटाएं)।
|
||||
❌ हटाने का समय संग्रह के आकार के समानुपाती होता है।
|
||||
|
||||
### लाभ
|
||||
|
||||
1. **ALLOW FILTERING को समाप्त करता है** - प्रत्येक क्वेरी में एक इष्टतम एक्सेस पथ होता है (सिवाय get_all स्कैन के)।
|
||||
2. **कोई द्वितीयक इंडेक्स नहीं** - प्रत्येक तालिका अपने क्वेरी पैटर्न के लिए इंडेक्स है।
|
||||
3. **बेहतर डेटा वितरण** - समग्र विभाजन कुंजियाँ प्रभावी रूप से लोड फैलाती हैं।
|
||||
4. **अनुमानित प्रदर्शन** - क्वेरी समय परिणाम के आकार के समानुपाती होता है, कुल डेटा के नहीं।
|
||||
5. **कैसेंड्रा की ताकत का लाभ उठाता है** - कैसेंड्रा के आर्किटेक्चर के लिए डिज़ाइन किया गया।
|
||||
6. **संग्रह हटाने को सक्षम बनाता है** - triples_collection हटाने के इंडेक्स के रूप में कार्य करता है।
|
||||
|
||||
## कार्यान्वयन योजना
|
||||
|
||||
### उन फ़ाइलों की आवश्यकता है जिनमें परिवर्तन आवश्यक हैं
|
||||
|
||||
#### प्राथमिक कार्यान्वयन फ़ाइल
|
||||
|
||||
**`trustgraph-flow/trustgraph/direct/cassandra_kg.py`** - पूर्ण पुनर्लेखन आवश्यक है।
|
||||
|
||||
**वर्तमान विधियाँ जिन्हें रिफैक्टर करने की आवश्यकता है:**
|
||||
```python
|
||||
# Schema initialization
|
||||
def init(self) -> None # Replace single table with three tables
|
||||
|
||||
# Insert operations
|
||||
def insert(self, collection, s, p, o) -> None # Write to all three tables
|
||||
|
||||
# Query operations (API unchanged, implementation optimized)
|
||||
def get_all(self, collection, limit=50) # Use triples_by_subject
|
||||
def get_s(self, collection, s, limit=10) # Use triples_by_subject
|
||||
def get_p(self, collection, p, limit=10) # Use triples_by_po
|
||||
def get_o(self, collection, o, limit=10) # Use triples_by_object
|
||||
def get_sp(self, collection, s, p, limit=10) # Use triples_by_subject
|
||||
def get_po(self, collection, p, o, limit=10) # Use triples_by_po (NO ALLOW FILTERING!)
|
||||
def get_os(self, collection, o, s, limit=10) # Use triples_by_subject
|
||||
def get_spo(self, collection, s, p, o, limit=10) # Use triples_by_subject
|
||||
|
||||
# Collection management
|
||||
def delete_collection(self, collection) -> None # Delete from all three tables
|
||||
```
|
||||
|
||||
#### एकीकरण फ़ाइलें (कोई लॉजिक परिवर्तन आवश्यक नहीं)
|
||||
|
||||
**`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`**
|
||||
कोई बदलाव आवश्यक नहीं - मौजूदा नॉलेज ग्राफ एपीआई का उपयोग करता है
|
||||
प्रदर्शन में स्वचालित सुधार से लाभ
|
||||
|
||||
**`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`**
|
||||
कोई बदलाव आवश्यक नहीं - मौजूदा नॉलेज ग्राफ एपीआई का उपयोग करता है
|
||||
प्रदर्शन में स्वचालित सुधार से लाभ
|
||||
|
||||
### अपडेट की आवश्यकता वाली परीक्षण फ़ाइलें
|
||||
|
||||
#### यूनिट टेस्ट
|
||||
**`tests/unit/test_storage/test_triples_cassandra_storage.py`**
|
||||
स्कीमा परिवर्तनों के लिए परीक्षण अपेक्षाओं को अपडेट करें
|
||||
मल्टी-टेबल स्थिरता के लिए परीक्षण जोड़ें
|
||||
क्वेरी योजनाओं में कोई ALLOW FILTERING न होने की पुष्टि करें
|
||||
|
||||
**`tests/unit/test_query/test_triples_cassandra_query.py`**
|
||||
प्रदर्शन दावों को अपडेट करें
|
||||
नए तालिकाओं के खिलाफ सभी 8 क्वेरी पैटर्न का परीक्षण करें
|
||||
सही तालिकाओं में क्वेरी रूटिंग की पुष्टि करें
|
||||
|
||||
#### एकीकरण परीक्षण
|
||||
**`tests/integration/test_cassandra_integration.py`**
|
||||
नए स्कीमा के साथ एंड-टू-एंड परीक्षण
|
||||
प्रदर्शन बेंचमार्किंग तुलना
|
||||
तालिकाओं में डेटा स्थिरता सत्यापन
|
||||
|
||||
**`tests/unit/test_storage/test_cassandra_config_integration.py`**
|
||||
स्कीमा सत्यापन परीक्षणों को अपडेट करें
|
||||
माइग्रेशन परिदृश्यों का परीक्षण करें
|
||||
|
||||
### कार्यान्वयन रणनीति
|
||||
|
||||
#### चरण 1: स्कीमा और कोर विधियाँ
|
||||
1. **`init()` विधि को फिर से लिखें** - एक के बजाय चार तालिकाओं का निर्माण करें
|
||||
2. **`insert()` विधि को फिर से लिखें** - सभी चार तालिकाओं में बैच राइट्स
|
||||
3. **तैयार कथनों को लागू करें** - इष्टतम प्रदर्शन के लिए
|
||||
4. **टेबल रूटिंग लॉजिक जोड़ें** - प्रश्नों को इष्टतम तालिकाओं पर निर्देशित करें
|
||||
5. **संग्रह हटाने को लागू करें** - triples_collection से पढ़ें, सभी तालिकाओं से बैच हटाएं
|
||||
|
||||
#### चरण 2: क्वेरी विधि अनुकूलन
|
||||
1. **प्रत्येक get_* विधि को फिर से लिखें** ताकि इष्टतम तालिका का उपयोग किया जा सके
|
||||
2. **सभी ALLOW FILTERING उपयोग को हटा दें**
|
||||
3. **कुशल क्लस्टरिंग कुंजी उपयोग को लागू करें**
|
||||
4. **क्वेरी प्रदर्शन लॉगिंग जोड़ें**
|
||||
|
||||
#### चरण 3: संग्रह प्रबंधन
|
||||
1. **`delete_collection()` को अपडेट करें** - सभी तीन तालिकाओं से हटाएं
|
||||
2. **संगति सत्यापन जोड़ें** - सुनिश्चित करें कि सभी तालिकाओं को सिंक में रखा जाए
|
||||
3. **बैच ऑपरेशंस लागू करें** - परमाणु मल्टी-टेबल ऑपरेशंस के लिए
|
||||
|
||||
### प्रमुख कार्यान्वयन विवरण
|
||||
|
||||
#### बैच राइट रणनीति
|
||||
```python
|
||||
def insert(self, collection, s, p, o):
|
||||
batch = BatchStatement()
|
||||
|
||||
# Insert into all four tables
|
||||
batch.add(self.insert_subject_stmt, (collection, s, p, o))
|
||||
batch.add(self.insert_po_stmt, (collection, p, o, s))
|
||||
batch.add(self.insert_object_stmt, (collection, o, s, p))
|
||||
batch.add(self.insert_collection_stmt, (collection, s, p, o))
|
||||
|
||||
self.session.execute(batch)
|
||||
```
|
||||
|
||||
#### प्रश्न रूटिंग लॉजिक (Query Routing Logic)
|
||||
```python
|
||||
def get_po(self, collection, p, o, limit=10):
|
||||
# Route to triples_p table - NO ALLOW FILTERING!
|
||||
return self.session.execute(
|
||||
self.get_po_stmt,
|
||||
(collection, p, o, limit)
|
||||
)
|
||||
|
||||
def get_spo(self, collection, s, p, o, limit=10):
|
||||
# Route to triples_collection table for exact SPO lookup
|
||||
return self.session.execute(
|
||||
self.get_spo_stmt,
|
||||
(collection, s, p, o, limit)
|
||||
)
|
||||
```
|
||||
|
||||
#### संग्रह हटाने का तर्क
|
||||
```python
|
||||
def delete_collection(self, collection):
|
||||
# Step 1: Read all triples from collection table
|
||||
rows = self.session.execute(
|
||||
f"SELECT s, p, o FROM {self.collection_table} WHERE collection = %s",
|
||||
(collection,)
|
||||
)
|
||||
|
||||
# Step 2: Batch delete from all 4 tables
|
||||
batch = BatchStatement()
|
||||
count = 0
|
||||
|
||||
for row in rows:
|
||||
s, p, o = row.s, row.p, row.o
|
||||
|
||||
# Delete using full partition keys for each table
|
||||
batch.add(SimpleStatement(
|
||||
f"DELETE FROM {self.subject_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
|
||||
), (collection, s, p, o))
|
||||
|
||||
batch.add(SimpleStatement(
|
||||
f"DELETE FROM {self.po_table} WHERE collection = ? AND p = ? AND o = ? AND s = ?"
|
||||
), (collection, p, o, s))
|
||||
|
||||
batch.add(SimpleStatement(
|
||||
f"DELETE FROM {self.object_table} WHERE collection = ? AND o = ? AND s = ? AND p = ?"
|
||||
), (collection, o, s, p))
|
||||
|
||||
batch.add(SimpleStatement(
|
||||
f"DELETE FROM {self.collection_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
|
||||
), (collection, s, p, o))
|
||||
|
||||
count += 1
|
||||
|
||||
# Execute every 100 triples to avoid oversized batches
|
||||
if count % 100 == 0:
|
||||
self.session.execute(batch)
|
||||
batch = BatchStatement()
|
||||
|
||||
# Execute remaining deletions
|
||||
if count % 100 != 0:
|
||||
self.session.execute(batch)
|
||||
|
||||
logger.info(f"Deleted {count} triples from collection {collection}")
|
||||
```
|
||||
|
||||
#### तैयार स्टेटमेंट अनुकूलन (तैयार कथन अनुकूलन)
|
||||
```python
|
||||
def prepare_statements(self):
|
||||
# Cache prepared statements for better performance
|
||||
self.insert_subject_stmt = self.session.prepare(
|
||||
f"INSERT INTO {self.subject_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
|
||||
)
|
||||
self.insert_po_stmt = self.session.prepare(
|
||||
f"INSERT INTO {self.po_table} (collection, p, o, s) VALUES (?, ?, ?, ?)"
|
||||
)
|
||||
self.insert_object_stmt = self.session.prepare(
|
||||
f"INSERT INTO {self.object_table} (collection, o, s, p) VALUES (?, ?, ?, ?)"
|
||||
)
|
||||
self.insert_collection_stmt = self.session.prepare(
|
||||
f"INSERT INTO {self.collection_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
|
||||
)
|
||||
# ... query statements
|
||||
```
|
||||
|
||||
## माइग्रेशन रणनीति
|
||||
|
||||
### डेटा माइग्रेशन दृष्टिकोण
|
||||
|
||||
#### विकल्प 1: ब्लू-ग्रीन परिनियोजन (अनुशंसित)
|
||||
1. **नए स्कीमा को मौजूदा स्कीमा के साथ तैनात करें** - अस्थायी रूप से अलग-अलग टेबल नामों का उपयोग करें
|
||||
2. **डबल-राइट अवधि** - संक्रमण के दौरान पुराने और नए दोनों स्कीमा में लिखें
|
||||
3. **बैकग्राउंड माइग्रेशन** - मौजूदा डेटा को नई तालिकाओं में कॉपी करें
|
||||
4. **रीड स्विच करें** - डेटा माइग्रेट होने के बाद प्रश्नों को नई तालिकाओं पर रूट करें
|
||||
5. **पुराने तालिकाओं को हटाएं** - सत्यापन अवधि के बाद
|
||||
|
||||
#### विकल्प 2: इन-प्लेस माइग्रेशन
|
||||
1. **स्कीमा जोड़ना** - मौजूदा कीस्पेस में नई तालिकाएँ बनाएँ
|
||||
2. **डेटा माइग्रेशन स्क्रिप्ट** - बैच कॉपी पुराने टेबल से नई तालिकाओं में
|
||||
3. **एप्लिकेशन अपडेट** - माइग्रेशन पूरा होने के बाद नया कोड तैनात करें
|
||||
4. **पुरानी टेबल की सफाई** - पुरानी टेबल और इंडेक्स हटाएं
|
||||
|
||||
### पश्चगामी अनुकूलता
|
||||
|
||||
#### परिनियोजन रणनीति
|
||||
```python
|
||||
# Environment variable to control table usage during migration
|
||||
USE_LEGACY_TABLES = os.getenv('CASSANDRA_USE_LEGACY', 'false').lower() == 'true'
|
||||
|
||||
class KnowledgeGraph:
|
||||
def __init__(self, ...):
|
||||
if USE_LEGACY_TABLES:
|
||||
self.init_legacy_schema()
|
||||
else:
|
||||
self.init_optimized_schema()
|
||||
```
|
||||
|
||||
#### माइग्रेशन स्क्रिप्ट
|
||||
```python
|
||||
def migrate_data():
|
||||
# Read from old table
|
||||
old_triples = session.execute("SELECT collection, s, p, o FROM triples")
|
||||
|
||||
# Batch write to new tables
|
||||
for batch in batched(old_triples, 100):
|
||||
batch_stmt = BatchStatement()
|
||||
for row in batch:
|
||||
# Add to all three new tables
|
||||
batch_stmt.add(insert_subject_stmt, row)
|
||||
batch_stmt.add(insert_po_stmt, (row.collection, row.p, row.o, row.s))
|
||||
batch_stmt.add(insert_object_stmt, (row.collection, row.o, row.s, row.p))
|
||||
session.execute(batch_stmt)
|
||||
```
|
||||
|
||||
### सत्यापन रणनीति
|
||||
|
||||
#### डेटा संगति जांच
|
||||
```python
|
||||
def validate_migration():
|
||||
# Count total records in old vs new tables
|
||||
old_count = session.execute("SELECT COUNT(*) FROM triples WHERE collection = ?", (collection,))
|
||||
new_count = session.execute("SELECT COUNT(*) FROM triples_by_subject WHERE collection = ?", (collection,))
|
||||
|
||||
assert old_count == new_count, f"Record count mismatch: {old_count} vs {new_count}"
|
||||
|
||||
# Spot check random samples
|
||||
sample_queries = generate_test_queries()
|
||||
for query in sample_queries:
|
||||
old_result = execute_legacy_query(query)
|
||||
new_result = execute_optimized_query(query)
|
||||
assert old_result == new_result, f"Query results differ for {query}"
|
||||
```
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
### प्रदर्शन परीक्षण
|
||||
|
||||
#### बेंचमार्क परिदृश्य
|
||||
1. **क्वेरी प्रदर्शन तुलना**
|
||||
सभी 8 क्वेरी प्रकारों के लिए पूर्व/पश्च प्रदर्शन मेट्रिक्स
|
||||
`get_po` प्रदर्शन सुधार पर ध्यान केंद्रित करें (ALLOW FILTERING को हटाना)
|
||||
विभिन्न डेटा आकारों के तहत क्वेरी विलंबता को मापें
|
||||
|
||||
2. **लोड परीक्षण**
|
||||
समवर्ती क्वेरी निष्पादन
|
||||
बैच ऑपरेशनों के साथ लेखन थ्रूपुट
|
||||
मेमोरी और सीपीयू उपयोग
|
||||
|
||||
3. **स्केलेबिलिटी परीक्षण**
|
||||
बढ़ते संग्रह आकारों के साथ प्रदर्शन
|
||||
मल्टी-कलेक्शन क्वेरी वितरण
|
||||
क्लस्टर नोड उपयोग
|
||||
|
||||
#### परीक्षण डेटा सेट
|
||||
**छोटा:** प्रति संग्रह 10K त्रिगुण
|
||||
**मध्यम:** प्रति संग्रह 100K त्रिगुण
|
||||
**बड़ा:** 1M+ त्रिगुण
|
||||
**एकाधिक संग्रह:** परीक्षण विभाजन वितरण
|
||||
|
||||
### कार्यात्मक परीक्षण
|
||||
|
||||
#### यूनिट टेस्ट अपडेट
|
||||
```python
|
||||
# Example test structure for new implementation
|
||||
class TestCassandraKGPerformance:
|
||||
def test_get_po_no_allow_filtering(self):
|
||||
# Verify get_po queries don't use ALLOW FILTERING
|
||||
with patch('cassandra.cluster.Session.execute') as mock_execute:
|
||||
kg.get_po('test_collection', 'predicate', 'object')
|
||||
executed_query = mock_execute.call_args[0][0]
|
||||
assert 'ALLOW FILTERING' not in executed_query
|
||||
|
||||
def test_multi_table_consistency(self):
|
||||
# Verify all tables stay in sync
|
||||
kg.insert('test', 's1', 'p1', 'o1')
|
||||
|
||||
# Check all tables contain the triple
|
||||
assert_triple_exists('triples_by_subject', 'test', 's1', 'p1', 'o1')
|
||||
assert_triple_exists('triples_by_po', 'test', 'p1', 'o1', 's1')
|
||||
assert_triple_exists('triples_by_object', 'test', 'o1', 's1', 'p1')
|
||||
```
|
||||
|
||||
#### एकीकरण परीक्षण अपडेट
|
||||
```python
|
||||
class TestCassandraIntegration:
|
||||
def test_query_performance_regression(self):
|
||||
# Ensure new implementation is faster than old
|
||||
old_time = benchmark_legacy_get_po()
|
||||
new_time = benchmark_optimized_get_po()
|
||||
assert new_time < old_time * 0.5 # At least 50% improvement
|
||||
|
||||
def test_end_to_end_workflow(self):
|
||||
# Test complete write -> query -> delete cycle
|
||||
# Verify no performance degradation in integration
|
||||
```
|
||||
|
||||
### रोलबैक योजना
|
||||
|
||||
#### त्वरित रोलबैक रणनीति
|
||||
1. **पर्यावरण चर स्विच** - तुरंत पुराने तालिकाओं पर वापस स्विच करें
|
||||
2. **पुराने तालिकाओं को बनाए रखें** - प्रदर्शन साबित होने तक उन्हें हटाएं नहीं
|
||||
3. **निगरानी अलर्ट** - त्रुटि दर/विलंबता के आधार पर स्वचालित रोलबैक ट्रिगर
|
||||
|
||||
#### रोलबैक सत्यापन
|
||||
```python
|
||||
def rollback_to_legacy():
|
||||
# Set environment variable
|
||||
os.environ['CASSANDRA_USE_LEGACY'] = 'true'
|
||||
|
||||
# Restart services to pick up change
|
||||
restart_cassandra_services()
|
||||
|
||||
# Validate functionality
|
||||
run_smoke_tests()
|
||||
```
|
||||
|
||||
## जोखिम और विचार
|
||||
|
||||
### प्रदर्शन जोखिम
|
||||
**लेखन विलंबता में वृद्धि** - प्रति सम्मिलित 4x लेखन संचालन (3-तालिका दृष्टिकोण से 33% अधिक)
|
||||
**भंडारण ओवरहेड** - 4x भंडारण आवश्यकता (3-तालिका दृष्टिकोण से 33% अधिक)
|
||||
**बैच लेखन विफलताएं** - उचित त्रुटि प्रबंधन की आवश्यकता
|
||||
**हटाने की जटिलता** - संग्रह हटाने के लिए रीड-देन-डिलीट लूप की आवश्यकता होती है
|
||||
|
||||
### परिचालन जोखिम
|
||||
**स्थानांतरण जटिलता** - बड़े डेटासेट के लिए डेटा स्थानांतरण
|
||||
**संगति चुनौतियां** - यह सुनिश्चित करना कि सभी तालिकाएं सिंक्रनाइज़ रहें
|
||||
**निगरानी अंतराल** - मल्टी-टेबल ऑपरेशनों के लिए नए मेट्रिक्स की आवश्यकता
|
||||
|
||||
### शमन रणनीतियाँ
|
||||
1. **धीरे-धीरे रोलआउट** - छोटे संग्रहों से शुरुआत करें
|
||||
2. **व्यापक निगरानी** - सभी प्रदर्शन मेट्रिक्स को ट्रैक करें
|
||||
3. **स्वचालित सत्यापन** - निरंतर संगति जांच
|
||||
4. **त्वरित रोलबैक क्षमता** - पर्यावरण-आधारित तालिका चयन
|
||||
|
||||
## सफलता मानदंड
|
||||
|
||||
### प्रदर्शन सुधार
|
||||
[ ] **ALLOW FILTERING को समाप्त करें** - get_po और get_os क्वेरी फ़िल्टरिंग के बिना चलती हैं
|
||||
[ ] **क्वेरी विलंबता में कमी** - क्वेरी प्रतिक्रिया समय में 50%+ सुधार
|
||||
[ ] **बेहतर लोड वितरण** - कोई हॉट विभाजन नहीं, क्लस्टर नोड्स में समान लोड
|
||||
[ ] **स्केलेबल प्रदर्शन** - क्वेरी समय परिणाम आकार के समानुपाती, कुल डेटा के समानुपाती नहीं
|
||||
|
||||
### कार्यात्मक आवश्यकताएँ
|
||||
[ ] **एपीआई संगतता** - सभी मौजूदा कोड अपरिवर्तित रूप से काम करना जारी रखता है
|
||||
[ ] **डेटा संगति** - तीनों तालिकाओं को सिंक्रनाइज़ रखा जाता है
|
||||
[ ] **कोई डेटा हानि नहीं** - माइग्रेशन सभी मौजूदा त्रिगुणों को संरक्षित करता है
|
||||
[ ] **पिछड़ा संगतता** - विरासत स्कीमा पर वापस रोलबैक करने की क्षमता
|
||||
|
||||
### परिचालन आवश्यकताएँ
|
||||
[ ] **सुरक्षित स्थानांतरण** - रोलबैक क्षमता के साथ ब्लू-ग्रीन परिनियोजन
|
||||
[ ] **निगरानी कवरेज** - मल्टी-टेबल ऑपरेशनों के लिए व्यापक मेट्रिक्स
|
||||
[ ] **परीक्षण कवरेज** - सभी क्वेरी पैटर्न प्रदर्शन बेंचमार्क के साथ परीक्षण किए गए
|
||||
[ ] **प्रलेखन** - अद्यतन परिनियोजन और परिचालन प्रक्रियाएं
|
||||
|
||||
## समयरेखा
|
||||
|
||||
### चरण 1: कार्यान्वयन
|
||||
[ ] मल्टी-टेबल स्कीमा के साथ `cassandra_kg.py` को फिर से लिखें
|
||||
[ ] बैच लेखन संचालन लागू करें
|
||||
[ ] तैयार स्टेटमेंट अनुकूलन जोड़ें
|
||||
[ ] यूनिट परीक्षण अपडेट करें
|
||||
|
||||
### चरण 2: एकीकरण परीक्षण
|
||||
[ ] एकीकरण परीक्षण अपडेट करें
|
||||
[ ] प्रदर्शन बेंचमार्किंग
|
||||
[ ] यथार्थवादी डेटा वॉल्यूम के साथ लोड परीक्षण
|
||||
[ ] डेटा संगति के लिए सत्यापन स्क्रिप्ट
|
||||
|
||||
### चरण 3: माइग्रेशन योजना
|
||||
[ ] ब्लू-ग्रीन परिनियोजन स्क्रिप्ट
|
||||
[ ] डेटा माइग्रेशन उपकरण
|
||||
[ ] निगरानी डैशबोर्ड अपडेट
|
||||
[ ] रोलबैक प्रक्रियाएं
|
||||
|
||||
### चरण 4: उत्पादन परिनियोजन
|
||||
[ ] उत्पादन में क्रमिक रोलआउट
|
||||
[ ] प्रदर्शन निगरानी और सत्यापन
|
||||
[ ] विरासत तालिका सफाई
|
||||
[ ] प्रलेखन अपडेट
|
||||
|
||||
## निष्कर्ष
|
||||
|
||||
यह मल्टी-टेबल डीनॉर्मलाइज़ेशन रणनीति दो महत्वपूर्ण प्रदर्शन बाधाओं को सीधे संबोधित करती है:
|
||||
|
||||
1. **महंगे ALLOW FILTERING को समाप्त करता है** प्रत्येक क्वेरी पैटर्न के लिए इष्टतम तालिका संरचनाएं प्रदान करके
|
||||
2. **बेहतर क्लस्टरिंग प्रभावशीलता** समग्र विभाजन कुंजियों के माध्यम से जो लोड को ठीक से वितरित करते हैं
|
||||
|
||||
यह दृष्टिकोण कैसेंड्रा की ताकत का लाभ उठाता है जबकि पूर्ण एपीआई संगतता बनाए रखता है, यह सुनिश्चित करता है कि मौजूदा कोड प्रदर्शन सुधारों से स्वचालित रूप से लाभान्वित होता है।
|
||||
410
docs/tech-specs/hi/collection-management.hi.md
Normal file
410
docs/tech-specs/hi/collection-management.hi.md
Normal file
|
|
@ -0,0 +1,410 @@
|
|||
---
|
||||
layout: default
|
||||
title: "संग्रह प्रबंधन तकनीकी विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# संग्रह प्रबंधन तकनीकी विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह विनिर्देश ट्रस्टग्राफ के लिए संग्रह प्रबंधन क्षमताओं का वर्णन करता है, जिसमें स्पष्ट संग्रह निर्माण की आवश्यकता होती है और संग्रह जीवनचक्र पर प्रत्यक्ष नियंत्रण प्रदान किया जाता है। उपयोग से पहले संग्रहों को स्पष्ट रूप से बनाया जाना चाहिए, जिससे लाइब्रेरियन मेटाडेटा और सभी स्टोरेज बैकएंड के बीच उचित सिंक्रोनाइज़ेशन सुनिश्चित हो सके। यह सुविधा चार प्राथमिक उपयोग मामलों का समर्थन करती है:
|
||||
|
||||
1. **संग्रह निर्माण**: डेटा संग्रहीत करने से पहले स्पष्ट रूप से संग्रह बनाएं
|
||||
2. **संग्रह सूची**: सिस्टम में सभी मौजूदा संग्रह देखें
|
||||
3. **संग्रह मेटाडेटा प्रबंधन**: संग्रह नामों, विवरणों और टैगों को अपडेट करें
|
||||
4. **संग्रह विलोपन**: संग्रह और उनके संबंधित डेटा को सभी स्टोरेज प्रकारों से हटा दें
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
**स्पष्ट संग्रह निर्माण**: डेटा संग्रहीत करने से पहले संग्रह बनाए जाने की आवश्यकता होती है
|
||||
**स्टोरेज सिंक्रोनाइज़ेशन**: सुनिश्चित करें कि संग्रह सभी स्टोरेज बैकएंड (वेक्टर, ऑब्जेक्ट, ट्रिपल) में मौजूद हैं
|
||||
**संग्रह दृश्यता**: उपयोगकर्ताओं को अपने वातावरण में सभी संग्रहों को सूचीबद्ध और निरीक्षण करने में सक्षम करें
|
||||
**संग्रह सफाई**: अब आवश्यक नहीं होने वाले संग्रहों को हटाने की अनुमति दें
|
||||
**संग्रह संगठन**: बेहतर संग्रह ट्रैकिंग और खोज के लिए लेबल और टैग का समर्थन करें
|
||||
**मेटाडेटा प्रबंधन**: परिचालन स्पष्टता के लिए संग्रहों के साथ सार्थक मेटाडेटा संबद्ध करें
|
||||
**संग्रह खोज**: फ़िल्टरिंग और खोज के माध्यम से विशिष्ट संग्रहों को खोजना आसान बनाएं
|
||||
**परिचालन पारदर्शिता**: संग्रह जीवनचक्र और उपयोग में स्पष्ट दृश्यता प्रदान करें
|
||||
**संसाधन प्रबंधन**: अप्रयुक्त संग्रहों को साफ करके संसाधन उपयोग को अनुकूलित करें
|
||||
**डेटा अखंडता**: स्टोरेज में मेटाडेटा ट्रैकिंग के बिना अनाथ संग्रहों को रोकें
|
||||
|
||||
## पृष्ठभूमि
|
||||
|
||||
पहले, ट्रस्टग्राफ में संग्रह डेटा लोडिंग कार्यों के दौरान निहित रूप से बनाए जाते थे, जिससे सिंक्रोनाइज़ेशन संबंधी समस्याएं होती थीं, जहाँ संग्रह स्टोरेज बैकएंड में मौजूद हो सकते थे लेकिन लाइब्रेरियन में संबंधित मेटाडेटा नहीं होता था। इससे प्रबंधन में चुनौतियां और संभावित अनाथ डेटा उत्पन्न होता था।
|
||||
|
||||
स्पष्ट संग्रह निर्माण मॉडल इन मुद्दों को संबोधित करता है:
|
||||
`tg-set-collection` के माध्यम से उपयोग से पहले संग्रह बनाने की आवश्यकता होती है
|
||||
सभी स्टोरेज बैकएंड में संग्रह निर्माण का प्रसारण
|
||||
लाइब्रेरियन मेटाडेटा और स्टोरेज के बीच सिंक्रोनाइज़ स्थिति बनाए रखना
|
||||
गैर-मौजूदा संग्रहों में लेखन को रोकना
|
||||
स्पष्ट संग्रह जीवनचक्र प्रबंधन प्रदान करना
|
||||
|
||||
यह विनिर्देश स्पष्ट संग्रह प्रबंधन मॉडल को परिभाषित करता है। स्पष्ट संग्रह निर्माण की आवश्यकता करके, ट्रस्टग्राफ यह सुनिश्चित करता है:
|
||||
संग्रह निर्माण से लाइब्रेरियन मेटाडेटा में ट्रैक किए जाते हैं
|
||||
सभी स्टोरेज बैकएंड डेटा प्राप्त करने से पहले संग्रहों के बारे में जानते हैं
|
||||
स्टोरेज में कोई अनाथ संग्रह नहीं है
|
||||
संग्रह जीवनचक्र पर स्पष्ट परिचालन दृश्यता और नियंत्रण
|
||||
गैर-मौजूदा संग्रहों को संदर्भित करने वाले कार्यों के लिए सुसंगत त्रुटि हैंडलिंग
|
||||
|
||||
## तकनीकी डिजाइन
|
||||
|
||||
### वास्तुकला
|
||||
|
||||
संग्रह प्रबंधन प्रणाली को मौजूदा ट्रस्टग्राफ बुनियादी ढांचे के भीतर लागू किया जाएगा:
|
||||
|
||||
1. **लाइब्रेरियन सेवा एकीकरण**
|
||||
संग्रह प्रबंधन संचालन मौजूदा लाइब्रेरियन सेवा में जोड़े जाएंगे
|
||||
किसी नई सेवा की आवश्यकता नहीं है - मौजूदा प्रमाणीकरण और एक्सेस पैटर्न का लाभ उठाता है
|
||||
संग्रह सूची, विलोपन और मेटाडेटा प्रबंधन को संभालता है
|
||||
|
||||
मॉड्यूल: trustgraph-librarian
|
||||
|
||||
2. **कैसेंड्रा संग्रह मेटाडेटा तालिका**
|
||||
मौजूदा लाइब्रेरियन कीस्पेस में एक नई तालिका
|
||||
उपयोगकर्ता-स्कोप किए गए एक्सेस के साथ संग्रह मेटाडेटा संग्रहीत करता है
|
||||
प्राथमिक कुंजी: उचित मल्टी-टेनेंसी के लिए (user_id, collection_id)
|
||||
|
||||
मॉड्यूल: trustgraph-librarian
|
||||
|
||||
3. **संग्रह प्रबंधन CLI**
|
||||
संग्रह संचालन के लिए कमांड-लाइन इंटरफ़ेस
|
||||
सूची, हटाएं, लेबल और टैग प्रबंधन कमांड प्रदान करता है
|
||||
मौजूदा CLI फ्रेमवर्क के साथ एकीकृत
|
||||
|
||||
मॉड्यूल: trustgraph-cli
|
||||
|
||||
### डेटा मॉडल
|
||||
|
||||
#### कैसेंड्रा संग्रह मेटाडेटा तालिका
|
||||
|
||||
संग्रह मेटाडेटा को लाइब्रेरियन कीस्पेस में एक संरचित कैसेंड्रा तालिका में संग्रहीत किया जाएगा:
|
||||
|
||||
```sql
|
||||
CREATE TABLE collections (
|
||||
user text,
|
||||
collection text,
|
||||
name text,
|
||||
description text,
|
||||
tags set<text>,
|
||||
created_at timestamp,
|
||||
updated_at timestamp,
|
||||
PRIMARY KEY (user, collection)
|
||||
);
|
||||
```
|
||||
|
||||
तालिका संरचना:
|
||||
**user**: **collection**: समग्र प्राथमिक कुंजी जो उपयोगकर्ता अलगाव सुनिश्चित करती है
|
||||
**name**: संग्रह का मानव-पठनीय नाम
|
||||
**description**: संग्रह के उद्देश्य का विस्तृत विवरण
|
||||
**tags**: वर्गीकरण और फ़िल्टरिंग के लिए टैग का सेट
|
||||
**created_at**: संग्रह निर्माण का टाइमस्टैम्प
|
||||
**updated_at**: अंतिम संशोधन टाइमस्टैम्प
|
||||
|
||||
यह दृष्टिकोण अनुमति देता है:
|
||||
उपयोगकर्ता अलगाव के साथ बहु-किरायेदार संग्रह प्रबंधन
|
||||
उपयोगकर्ता और संग्रह द्वारा कुशल क्वेरी
|
||||
संगठन के लिए लचीला टैगिंग सिस्टम
|
||||
परिचालन अंतर्दृष्टि के लिए जीवनचक्र ट्रैकिंग
|
||||
|
||||
#### संग्रह जीवनचक्र
|
||||
|
||||
डेटा संचालन शुरू करने से पहले संग्रह को स्पष्ट रूप से लाइब्रेरियन में बनाया जाना चाहिए:
|
||||
|
||||
1. **संग्रह निर्माण** (दो रास्ते):
|
||||
|
||||
**रास्ता A: उपयोगकर्ता-आरंभित निर्माण** `tg-set-collection` के माध्यम से:
|
||||
उपयोगकर्ता संग्रह आईडी, नाम, विवरण और टैग प्रदान करता है
|
||||
लाइब्रेरियन `collections` तालिका में मेटाडेटा रिकॉर्ड बनाता है
|
||||
लाइब्रेरियन सभी स्टोरेज बैकएंड पर "create-collection" प्रसारित करता है
|
||||
सभी स्टोरेज प्रोसेसर संग्रह बनाते हैं और सफलता की पुष्टि करते हैं
|
||||
संग्रह अब डेटा संचालन के लिए तैयार है
|
||||
|
||||
**रास्ता B: दस्तावेज़ सबमिशन पर स्वचालित निर्माण**:
|
||||
उपयोगकर्ता एक संग्रह आईडी निर्दिष्ट करते हुए एक दस्तावेज़ सबमिट करता है
|
||||
लाइब्रेरियन जांचता है कि क्या संग्रह मेटाडेटा तालिका में मौजूद है
|
||||
यदि मौजूद नहीं है: लाइब्रेरियन डिफ़ॉल्ट के साथ मेटाडेटा बनाता है (नाम = संग्रह_आईडी, खाली विवरण/टैग)
|
||||
लाइब्रेरियन सभी स्टोरेज बैकएंड पर "create-collection" प्रसारित करता है
|
||||
सभी स्टोरेज प्रोसेसर संग्रह बनाते हैं और सफलता की पुष्टि करते हैं
|
||||
दस्तावेज़ प्रसंस्करण संग्रह स्थापित होने के साथ आगे बढ़ता है
|
||||
|
||||
दोनों रास्ते यह सुनिश्चित करते हैं कि संग्रह लाइब्रेरियन मेटाडेटा में और सभी स्टोरेज बैकएंड में मौजूद है, डेटा संचालन से पहले।
|
||||
|
||||
2. **भंडारण सत्यापन**: लेखन संचालन संग्रह के अस्तित्व को मान्य करते हैं:
|
||||
स्टोरेज प्रोसेसर लेखन स्वीकार करने से पहले संग्रह की स्थिति की जांच करते हैं
|
||||
गैर-मौजूदा संग्रह में लेखन त्रुटि लौटाते हैं
|
||||
यह लाइब्रेरियन के संग्रह निर्माण तर्क को बायपास करने वाले सीधे लेखन को रोकता है
|
||||
|
||||
3. **क्वेरी व्यवहार**: क्वेरी संचालन गैर-मौजूदा संग्रह को सुचारू रूप से संभालते हैं:
|
||||
गैर-मौजूदा संग्रह में क्वेरी खाली परिणाम लौटाती है
|
||||
कोई त्रुटि नहीं फेंकी जाती है क्वेरी संचालन के लिए
|
||||
संग्रह के मौजूद होने की आवश्यकता के बिना अन्वेषण की अनुमति देता है
|
||||
|
||||
4. **मेटाडेटा अपडेट**: उपयोगकर्ता निर्माण के बाद संग्रह मेटाडेटा को अपडेट कर सकते हैं:
|
||||
`tg-set-collection` के माध्यम से नाम, विवरण और टैग अपडेट करें
|
||||
अपडेट केवल लाइब्रेरियन मेटाडेटा पर लागू होते हैं
|
||||
स्टोरेज बैकएंड संग्रह बनाए रखते हैं लेकिन मेटाडेटा अपडेट प्रसारित नहीं होते हैं
|
||||
|
||||
5. **स्पष्ट विलोपन**: उपयोगकर्ता `tg-delete-collection` के माध्यम से संग्रह को हटाते हैं:
|
||||
लाइब्रेरियन सभी स्टोरेज बैकएंड पर "delete-collection" प्रसारित करता है
|
||||
सभी स्टोरेज प्रोसेसर से पुष्टिकरण की प्रतीक्षा करता है
|
||||
केवल स्टोरेज क्लीनअप पूरा होने के बाद लाइब्रेरियन मेटाडेटा रिकॉर्ड को हटाता है
|
||||
यह सुनिश्चित करता है कि कोई भी डेटा स्टोरेज में नहीं बचा है
|
||||
|
||||
**मुख्य सिद्धांत**: लाइब्रेरियन संग्रह निर्माण के लिए एकल नियंत्रण बिंदु है। चाहे उपयोगकर्ता कमांड द्वारा शुरू किया गया हो या दस्तावेज़ सबमिशन द्वारा, लाइब्रेरियन डेटा संचालन की अनुमति देने से पहले उचित मेटाडेटा ट्रैकिंग और स्टोरेज बैकएंड सिंक्रोनाइज़ेशन सुनिश्चित करता है।
|
||||
|
||||
आवश्यक संचालन:
|
||||
**संग्रह बनाएं**: `tg-set-collection` के माध्यम से उपयोगकर्ता ऑपरेशन या दस्तावेज़ सबमिशन पर स्वचालित
|
||||
**संग्रह मेटाडेटा अपडेट करें**: नाम, विवरण और टैग को संशोधित करने के लिए उपयोगकर्ता ऑपरेशन
|
||||
**संग्रह हटाएं**: सभी स्टोर में संग्रह और उसके डेटा को हटाने के लिए उपयोगकर्ता ऑपरेशन
|
||||
**संग्रह सूचीबद्ध करें**: टैग द्वारा फ़िल्टर करके संग्रह देखने के लिए उपयोगकर्ता ऑपरेशन
|
||||
|
||||
#### मल्टी-स्टोर संग्रह प्रबंधन
|
||||
|
||||
संग्रह ट्रस्टग्राफ में कई स्टोरेज बैकएंड में मौजूद हैं:
|
||||
**वेक्टर स्टोर** (Qdrant, Milvus, Pinecone): एम्बेडिंग और वेक्टर डेटा संग्रहीत करें
|
||||
**ऑब्जेक्ट स्टोर** (Cassandra): दस्तावेज़ और फ़ाइल डेटा संग्रहीत करें
|
||||
**ट्रिपल स्टोर** (Cassandra, Neo4j, Memgraph, FalkorDB): ग्राफ/RDF डेटा संग्रहीत करें
|
||||
|
||||
प्रत्येक स्टोर प्रकार निम्नलिखित लागू करता है:
|
||||
**संग्रह स्थिति ट्रैकिंग**: यह जानकारी बनाए रखें कि कौन से संग्रह मौजूद हैं
|
||||
**संग्रह निर्माण**: "संग्रह बनाएं" संचालन स्वीकार करें और संसाधित करें
|
||||
**संग्रह सत्यापन**: लिखने को स्वीकार करने से पहले जांचें कि संग्रह मौजूद है या नहीं
|
||||
**संग्रह विलोपन**: निर्दिष्ट संग्रह के लिए सभी डेटा हटाएं
|
||||
|
||||
लाइब्रेरियन सेवा सभी स्टोर प्रकारों में संग्रह संचालन का समन्वय करती है, यह सुनिश्चित करते हुए:
|
||||
सभी बैकएंड में संग्रह का निर्माण उपयोग से पहले किया जाता है
|
||||
सभी बैकएंड निर्माण की पुष्टि करते हैं इससे पहले कि सफलता वापस की जाए
|
||||
भंडारण प्रकारों में संग्रह जीवनचक्र का सिंक्रनाइज़ेशन
|
||||
जब संग्रह मौजूद नहीं होते हैं तो सुसंगत त्रुटि हैंडलिंग
|
||||
|
||||
#### संग्रहण स्थिति ट्रैकिंग, संग्रहण प्रकार द्वारा
|
||||
|
||||
प्रत्येक संग्रहण बैकएंड अपनी क्षमताओं के आधार पर संग्रह स्थिति को अलग-अलग तरीके से ट्रैक करता है:
|
||||
|
||||
**कैसेंड्रा ट्रिपल स्टोर:**
|
||||
मौजूदा `triples_collection` तालिका का उपयोग करता है
|
||||
संग्रह बनने पर सिस्टम मार्कर ट्रिपल बनाता है
|
||||
क्वेरी: `SELECT collection FROM triples_collection WHERE collection = ? LIMIT 1`
|
||||
संग्रह के अस्तित्व की जांच के लिए कुशल सिंगल-पार्टिशन चेक
|
||||
|
||||
**Qdrant/Milvus/Pinecone वेक्टर स्टोर:**
|
||||
मूल संग्रह एपीआई अस्तित्व जांच प्रदान करते हैं
|
||||
उचित वेक्टर कॉन्फ़िगरेशन के साथ संग्रह बनाए जाते हैं
|
||||
`collection_exists()` विधि संग्रहण एपीआई का उपयोग करती है
|
||||
संग्रह निर्माण आयाम आवश्यकताओं को मान्य करता है
|
||||
|
||||
**Neo4j/Memgraph/FalkorDB ग्राफ स्टोर:**
|
||||
संग्रह को ट्रैक करने के लिए `:CollectionMetadata` नोड्स का उपयोग करें
|
||||
नोड गुण: `{user, collection, created_at}`
|
||||
क्वेरी: `MATCH (c:CollectionMetadata {user: $user, collection: $collection})`
|
||||
डेटा नोड्स से अलग, स्पष्ट अलगाव के लिए
|
||||
कुशल संग्रह लिस्टिंग और सत्यापन को सक्षम करता है
|
||||
|
||||
**कैसेंड्रा ऑब्जेक्ट स्टोर:**
|
||||
संग्रह मेटाडेटा तालिका या मार्कर पंक्तियों का उपयोग करता है
|
||||
ट्रिपल स्टोर के समान पैटर्न
|
||||
दस्तावेज़ लेखन से पहले संग्रह को मान्य करता है
|
||||
|
||||
### एपीआई
|
||||
|
||||
संग्रह प्रबंधन एपीआई (लाइब्रेरियन):
|
||||
**संग्रह बनाएं/अपडेट करें**: `tg-set-collection` के माध्यम से एक नया संग्रह बनाएं या मौजूदा मेटाडेटा को अपडेट करें
|
||||
**संग्रह सूचीबद्ध करें**: वैकल्पिक टैग फ़िल्टरिंग के साथ एक उपयोगकर्ता के लिए संग्रह पुनर्प्राप्त करें
|
||||
**संग्रह हटाएं**: संग्रह और उससे जुड़े डेटा को हटाएं, सभी स्टोर प्रकारों में कैस्केड करें
|
||||
|
||||
संग्रहण प्रबंधन एपीआई (सभी संग्रहण प्रोसेसर):
|
||||
**संग्रह बनाएं**: "संग्रह बनाएं" ऑपरेशन को संभालें, संग्रहण में संग्रह स्थापित करें
|
||||
**संग्रह हटाएं**: "संग्रह हटाएं" ऑपरेशन को संभालें, सभी संग्रह डेटा को हटाएं
|
||||
**संग्रह मौजूद है जांच**: लेखन संचालन को स्वीकार करने से पहले आंतरिक सत्यापन
|
||||
|
||||
डेटा ऑपरेशन एपीआई (संशोधित व्यवहार):
|
||||
**लिखने एपीआई**: डेटा स्वीकार करने से पहले जांचें कि संग्रह मौजूद है या नहीं, यदि नहीं तो त्रुटि लौटाएं
|
||||
**क्वेरी एपीआई**: त्रुटि के बिना गैर-मौजूद संग्रह के लिए खाली परिणाम लौटाएं
|
||||
|
||||
### कार्यान्वयन विवरण
|
||||
|
||||
कार्यान्वयन सेवा एकीकरण और CLI कमांड संरचना के लिए मौजूदा ट्रस्टग्राफ पैटर्न का पालन करेगा।
|
||||
|
||||
#### संग्रह विलोपन कैस्केड
|
||||
|
||||
जब कोई उपयोगकर्ता लाइब्रेरियन सेवा के माध्यम से संग्रह विलोपन शुरू करता है:
|
||||
|
||||
1. **मेटाडेटा सत्यापन**: सत्यापित करें कि संग्रह मौजूद है और उपयोगकर्ता के पास हटाने की अनुमति है
|
||||
2. **स्टोर कैस्केड**: लाइब्रेरियन सभी स्टोर लेखकों में विलोपन का समन्वय करता है:
|
||||
वेक्टर स्टोर लेखक: उपयोगकर्ता और संग्रह के लिए एम्बेडिंग और वेक्टर इंडेक्स हटाएं
|
||||
ऑब्जेक्ट स्टोर लेखक: उपयोगकर्ता और संग्रह के लिए दस्तावेज़ और फ़ाइलें हटाएं
|
||||
ट्रिपल स्टोर लेखक: उपयोगकर्ता और संग्रह के लिए ग्राफ डेटा और ट्रिपल हटाएं
|
||||
3. **मेटाडेटा सफाई**: कैसेंड्रा से संग्रह मेटाडेटा रिकॉर्ड हटाएं
|
||||
4. **त्रुटि हैंडलिंग**: यदि किसी भी स्टोर विलोपन में विफलता होती है, तो रोलबैक या पुनः प्रयास तंत्र के माध्यम से स्थिरता बनाए रखें
|
||||
|
||||
#### संग्रह प्रबंधन इंटरफ़ेस
|
||||
|
||||
⚠️ लेगेसी अप्रोच - कॉन्फ़िग-आधारित पैटर्न द्वारा प्रतिस्थापित
|
||||
|
||||
नीचे वर्णित कतार-आधारित आर्किटेक्चर को `CollectionConfigHandler` का उपयोग करके एक कॉन्फ़िग-आधारित दृष्टिकोण से बदल दिया गया है। अब सभी संग्रहण बैकएंड समर्पित प्रबंधन कतारों के बजाय कॉन्फ़िग पुश संदेशों के माध्यम से संग्रह अपडेट प्राप्त करते हैं।
|
||||
|
||||
~~सभी स्टोर लेखक एक मानकीकृत संग्रह प्रबंधन इंटरफ़ेस को लागू करते हैं जिसमें एक सामान्य स्कीमा है:~~
|
||||
|
||||
~~**संदेश स्कीमा (`StorageManagementRequest`):~~
|
||||
```json
|
||||
{
|
||||
"operation": "create-collection" | "delete-collection",
|
||||
"user": "user123",
|
||||
"collection": "documents-2024"
|
||||
}
|
||||
```
|
||||
|
||||
~~**क्यू आर्किटेक्चर:**~~
|
||||
~~**वेक्टर स्टोर मैनेजमेंट क्यू** (`vector-storage-management`): वेक्टर/एम्बेडिंग स्टोर~~
|
||||
~~**ऑब्जेक्ट स्टोर मैनेजमेंट क्यू** (`object-storage-management`): ऑब्जेक्ट/डॉक्यूमेंट स्टोर~~
|
||||
~~**ट्रिपल स्टोर मैनेजमेंट क्यू** (`triples-storage-management`): ग्राफ/आरडीएफ स्टोर~~
|
||||
~~**स्टोरेज रिस्पांस क्यू** (`storage-management-response`): सभी प्रतिक्रियाएं यहां भेजी जाती हैं~~
|
||||
|
||||
**वर्तमान कार्यान्वयन:**
|
||||
|
||||
सभी स्टोरेज बैकएंड अब `CollectionConfigHandler` का उपयोग करते हैं:
|
||||
**कॉन्फ़िग पुश इंटीग्रेशन**: स्टोरेज सेवाएं कॉन्फ़िग पुश नोटिफिकेशन के लिए पंजीकरण करती हैं
|
||||
**स्वचालित सिंक्रोनाइज़ेशन**: कॉन्फ़िग परिवर्तनों के आधार पर संग्रह बनाए/हटाए जाते हैं
|
||||
**घोषणात्मक मॉडल**: संग्रह कॉन्फ़िग सेवा में परिभाषित हैं, बैकएंड मिलान के लिए सिंक्रोनाइज़ होते हैं
|
||||
**कोई अनुरोध/प्रतिक्रिया नहीं**: समन्वय ओवरहेड और प्रतिक्रिया ट्रैकिंग को समाप्त करता है
|
||||
**संग्रह स्थिति ट्रैकिंग**: `known_collections` कैश के माध्यम से बनाए रखा जाता है
|
||||
**आइडेंपोटेंट ऑपरेशन**: एक ही कॉन्फ़िग को कई बार संसाधित करना सुरक्षित है
|
||||
|
||||
प्रत्येक स्टोरेज बैकएंड लागू करता है:
|
||||
`create_collection(user: str, collection: str, metadata: dict)` - संग्रह संरचनाएं बनाएं
|
||||
`delete_collection(user: str, collection: str)` - सभी संग्रह डेटा हटाएं
|
||||
`collection_exists(user: str, collection: str) -> bool` - लिखने से पहले मान्य करें
|
||||
|
||||
#### कैसेंड्रा ट्रिपल स्टोर रीफैक्टर
|
||||
|
||||
इस कार्यान्वयन के हिस्से के रूप में, कैसेंड्रा ट्रिपल स्टोर को एक टेबल-प्रति-संग्रह मॉडल से एक एकीकृत टेबल मॉडल में रीफैक्टर किया जाएगा:
|
||||
|
||||
**वर्तमान आर्किटेक्चर:**
|
||||
प्रति उपयोगकर्ता की स्पेस, प्रत्येक संग्रह के लिए अलग टेबल
|
||||
स्कीमा: `(s, p, o)` with `PRIMARY KEY (s, p, o)`
|
||||
टेबल नाम: उपयोगकर्ता संग्रह अलग-अलग कैसेंड्रा टेबल बन जाते हैं
|
||||
|
||||
**नया आर्किटेक्चर:**
|
||||
प्रति उपयोगकर्ता की स्पेस, सभी संग्रहों के लिए एक सिंगल "ट्रिपल्स" टेबल
|
||||
स्कीमा: `(collection, s, p, o)` with `PRIMARY KEY (collection, s, p, o)`
|
||||
संग्रह विभाजन के माध्यम से संग्रह अलगाव
|
||||
|
||||
**आवश्यक परिवर्तन:**
|
||||
|
||||
1. **ट्रस्टग्राफ क्लास रीफैक्टर** (`trustgraph/direct/cassandra.py`):
|
||||
कंस्ट्रक्टर से `table` पैरामीटर हटाएं, फिक्स्ड "ट्रिपल्स" टेबल का उपयोग करें
|
||||
सभी विधियों में `collection` पैरामीटर जोड़ें
|
||||
स्कीमा को संग्रह को पहले कॉलम के रूप में शामिल करने के लिए अपडेट करें
|
||||
**इंडेक्स अपडेट**: सभी 8 क्वेरी पैटर्न का समर्थन करने के लिए नए इंडेक्स बनाए जाएंगे:
|
||||
विषय-आधारित प्रश्नों के लिए `(s)` पर इंडेक्स
|
||||
विधेय-आधारित प्रश्नों के लिए `(p)` पर इंडेक्स
|
||||
ऑब्जेक्ट-आधारित प्रश्नों के लिए `(o)` पर इंडेक्स
|
||||
ध्यान दें: कैसेंड्रा मल्टी-कॉलम सेकेंडरी इंडेक्स का समर्थन नहीं करता है, इसलिए ये सिंगल-कॉलम इंडेक्स हैं
|
||||
|
||||
**क्वेरी पैटर्न प्रदर्शन:**
|
||||
✅ `get_all()` - `collection` पर विभाजन स्कैन
|
||||
✅ `get_s(s)` - प्राथमिक कुंजी का कुशलतापूर्वक उपयोग करता है (`collection, s`)
|
||||
✅ `get_p(p)` - `idx_p` का उपयोग `collection` फ़िल्टरिंग के साथ
|
||||
✅ `get_o(o)` - `idx_o` का उपयोग `collection` फ़िल्टरिंग के साथ
|
||||
✅ `get_sp(s, p)` - प्राथमिक कुंजी का कुशलतापूर्वक उपयोग करता है (`collection, s, p`)
|
||||
⚠️ `get_po(p, o)` - `ALLOW FILTERING` की आवश्यकता है (या तो `idx_p` या `idx_o` प्लस फ़िल्टरिंग का उपयोग करता है)
|
||||
✅ `get_os(o, s)` - `idx_o` का उपयोग अतिरिक्त फ़िल्टरिंग के साथ `s` पर
|
||||
✅ `get_spo(s, p, o)` - पूरी प्राथमिक कुंजी का कुशलतापूर्वक उपयोग करता है
|
||||
|
||||
**ALLOW FILTERING पर नोट:** `get_po` क्वेरी पैटर्न को `ALLOW FILTERING` की आवश्यकता होती है क्योंकि इसे उपयुक्त कंपाउंड इंडेक्स के बिना विधेय और ऑब्जेक्ट बाधाओं दोनों की आवश्यकता होती है। यह स्वीकार्य है क्योंकि यह क्वेरी पैटर्न विशिष्ट ट्रिपल स्टोर उपयोग में विषय-आधारित प्रश्नों की तुलना में कम सामान्य है
|
||||
|
||||
2. **स्टोरेज राइटर अपडेट** (`trustgraph/storage/triples/cassandra/write.py`):
|
||||
प्रति (उपयोगकर्ता, संग्रह) के बजाय प्रति उपयोगकर्ता सिंगल ट्रस्टग्राफ कनेक्शन बनाए रखें
|
||||
सम्मिलित कार्यों में संग्रह पास करें
|
||||
कम कनेक्शन के साथ बेहतर संसाधन उपयोग
|
||||
|
||||
3. **क्वेरी सर्विस अपडेट** (`trustgraph/query/triples/cassandra/service.py`):
|
||||
प्रति उपयोगकर्ता सिंगल ट्रस्टग्राफ कनेक्शन
|
||||
सभी क्वेरी कार्यों में संग्रह पास करें
|
||||
संग्रह पैरामीटर के साथ समान क्वेरी लॉजिक बनाए रखें
|
||||
|
||||
**लाभ:**
|
||||
**सरलीकृत संग्रह विलोपन:** सभी 4 तालिकाओं में `collection` विभाजन कुंजी का उपयोग करके हटाएं
|
||||
**संसाधन दक्षता:** कम डेटाबेस कनेक्शन और टेबल ऑब्जेक्ट
|
||||
**क्रॉस-संग्रह संचालन:** कई संग्रहों को कवर करने वाले संचालन को लागू करना आसान है
|
||||
**संगत आर्किटेक्चर:** एकीकृत संग्रह मेटाडेटा दृष्टिकोण के साथ संरेखित
|
||||
**संग्रह सत्यापन:** `triples_collection` टेबल के माध्यम से संग्रह अस्तित्व की जांच करना आसान है
|
||||
|
||||
संग्रह संचालन संभव होने पर परमाणु होंगे और उचित त्रुटि प्रबंधन और सत्यापन प्रदान करेंगे।
|
||||
|
||||
## सुरक्षा संबंधी विचार
|
||||
|
||||
संग्रह प्रबंधन कार्यों के लिए उचित प्राधिकरण की आवश्यकता होती है ताकि अनधिकृत पहुंच या संग्रहों के हटाने को रोका जा सके। पहुंच नियंत्रण मौजूदा ट्रस्टग्राफ सुरक्षा मॉडल के अनुरूप होगा।
|
||||
|
||||
## प्रदर्शन संबंधी विचार
|
||||
|
||||
बड़ी संख्या में संग्रहों वाले वातावरण में संग्रह सूची संचालन के लिए पेजिंग की आवश्यकता हो सकती है। सामान्य फ़िल्टरिंग पैटर्न के लिए मेटाडेटा प्रश्नों को अनुकूलित किया जाना चाहिए।
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
व्यापक परीक्षण में शामिल होंगे:
|
||||
संग्रह निर्माण वर्कफ़्लो का एंड-टू-एंड परीक्षण
|
||||
स्टोरेज बैकएंड सिंक्रोनाइज़ेशन
|
||||
गैर-मौजूदा संग्रहों के लिए लेखन सत्यापन
|
||||
गैर-मौजूदा संग्रहों के लिए क्वेरी हैंडलिंग
|
||||
सभी स्टोरों में संग्रह हटाने का क्रम
|
||||
त्रुटि प्रबंधन और पुनर्प्राप्ति परिदृश्य
|
||||
प्रत्येक स्टोरेज बैकएंड के लिए यूनिट परीक्षण
|
||||
क्रॉस-स्टोर संचालन के लिए एकीकरण परीक्षण
|
||||
|
||||
## कार्यान्वयन स्थिति
|
||||
|
||||
### ✅ पूर्ण घटक
|
||||
|
||||
1. **लाइब्रेरियन संग्रह प्रबंधन सेवा** (`trustgraph-flow/trustgraph/librarian/collection_manager.py`)
|
||||
संग्रह मेटाडेटा CRUD संचालन (सूची, अपडेट, हटाएं)
|
||||
`LibraryTableStore` के माध्यम से कैसेंड्रा संग्रह मेटाडेटा तालिका एकीकरण
|
||||
सभी स्टोरेज प्रकारों में संग्रह हटाने का समन्वय
|
||||
उचित त्रुटि प्रबंधन के साथ एसिंक्रोनस अनुरोध/प्रतिक्रिया हैंडलिंग
|
||||
|
||||
2. **संग्रह मेटाडेटा स्कीमा** (`trustgraph-base/trustgraph/schema/services/collection.py`)
|
||||
`CollectionManagementRequest` और `CollectionManagementResponse` स्कीमा
|
||||
संग्रह रिकॉर्ड के लिए `CollectionMetadata` स्कीमा
|
||||
संग्रह अनुरोध/प्रतिक्रिया कतार विषय परिभाषाएँ
|
||||
|
||||
3. **स्टोरेज प्रबंधन स्कीमा** (`trustgraph-base/trustgraph/schema/services/storage.py`)
|
||||
`StorageManagementRequest` और `StorageManagementResponse` स्कीमा
|
||||
स्टोरेज प्रबंधन कतार विषय परिभाषित
|
||||
स्टोरेज-स्तरीय संग्रह संचालन के लिए संदेश प्रारूप
|
||||
|
||||
4. **कैसेंड्रा 4-टेबल स्कीमा** (`trustgraph-flow/trustgraph/direct/cassandra_kg.py`)
|
||||
क्वेरी प्रदर्शन के लिए कंपाउंड पार्टीशन कुंजी
|
||||
SPO प्रश्नों और हटाने ट्रैकिंग के लिए `triples_collection` तालिका
|
||||
संग्रह हटाने को रीड-देन-डिलीट पैटर्न के साथ लागू किया गया
|
||||
|
||||
### ✅ कॉन्फ़िग-आधारित पैटर्न में माइग्रेशन - पूर्ण
|
||||
|
||||
**सभी स्टोरेज बैकएंड को कतार-आधारित पैटर्न से कॉन्फ़िग-आधारित `CollectionConfigHandler` पैटर्न में माइग्रेट किया गया है।**
|
||||
|
||||
माइग्रेशन पूर्ण:
|
||||
✅ `trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/triples/neo4j/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/triples/memgraph/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/triples/falkordb/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/doc_embeddings/qdrant/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/graph_embeddings/qdrant/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/doc_embeddings/milvus/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/graph_embeddings/milvus/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/doc_embeddings/pinecone/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/graph_embeddings/pinecone/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/objects/cassandra/write.py`
|
||||
|
||||
सभी बैकएंड अब:
|
||||
`CollectionConfigHandler` से विरासत में मिला है
|
||||
`self.register_config_handler(self.on_collection_config)` के माध्यम से कॉन्फ़िग पुश नोटिफिकेशन के लिए पंजीकरण करें
|
||||
`create_collection(user, collection, metadata)` और `delete_collection(user, collection)` को लागू करें
|
||||
लिखने से पहले `collection_exists(user, collection)` का उपयोग करके सत्यापन करें
|
||||
कॉन्फ़िग सेवा परिवर्तनों के साथ स्वचालित रूप से सिंक करें
|
||||
|
||||
विरासत कतार-आधारित बुनियादी ढांचा हटाया गया:
|
||||
✅ `StorageManagementRequest` और `StorageManagementResponse` स्कीमा हटाए गए
|
||||
✅ स्टोरेज प्रबंधन कतार विषय परिभाषाएँ हटाई गईं
|
||||
✅ सभी बैकएंड से स्टोरेज प्रबंधन उपभोक्ता/उत्पादक हटाए गए
|
||||
✅ सभी बैकएंड से `on_storage_management` हैंडलर हटाए गए
|
||||
144
docs/tech-specs/hi/document-embeddings-chunk-id.hi.md
Normal file
144
docs/tech-specs/hi/document-embeddings-chunk-id.hi.md
Normal file
|
|
@ -0,0 +1,144 @@
|
|||
---
|
||||
layout: default
|
||||
title: "दस्तावेज़ एम्बेडिंग चंक आईडी"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# दस्तावेज़ एम्बेडिंग चंक आईडी
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
वर्तमान में, दस्तावेज़ एम्बेडिंग स्टोरेज चंक टेक्स्ट को सीधे वेक्टर स्टोर पेलोड में संग्रहीत करता है, जिससे गैरेज में मौजूद डेटा दोहराया जाता है। यह विनिर्देश चंक टेक्स्ट स्टोरेज को `chunk_id` संदर्भों से बदल देता है।
|
||||
|
||||
## वर्तमान स्थिति
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class ChunkEmbeddings:
|
||||
chunk: bytes = b""
|
||||
vectors: list[list[float]] = field(default_factory=list)
|
||||
|
||||
@dataclass
|
||||
class DocumentEmbeddingsResponse:
|
||||
error: Error | None = None
|
||||
chunks: list[str] = field(default_factory=list)
|
||||
```
|
||||
|
||||
वेक्टर स्टोर पेलोड:
|
||||
```python
|
||||
payload={"doc": chunk} # Duplicates Garage content
|
||||
```
|
||||
|
||||
## डिज़ाइन
|
||||
|
||||
### स्कीमा में बदलाव
|
||||
|
||||
**ChunkEmbeddings** - "chunk" को "chunk_id" से बदलें:
|
||||
```python
|
||||
@dataclass
|
||||
class ChunkEmbeddings:
|
||||
chunk_id: str = ""
|
||||
vectors: list[list[float]] = field(default_factory=list)
|
||||
```
|
||||
|
||||
**DocumentEmbeddingsResponse** - चंक्स के बजाय chunk_ids लौटाएं:
|
||||
```python
|
||||
@dataclass
|
||||
class DocumentEmbeddingsResponse:
|
||||
error: Error | None = None
|
||||
chunk_ids: list[str] = field(default_factory=list)
|
||||
```
|
||||
|
||||
### वेक्टर स्टोर पेलोड
|
||||
|
||||
सभी स्टोर (क्यूड्रेंट, मिल्वस, पाइनकोन):
|
||||
```python
|
||||
payload={"chunk_id": chunk_id}
|
||||
```
|
||||
|
||||
### दस्तावेज़ आरएजी (RAG) में बदलाव
|
||||
|
||||
दस्तावेज़ आरएजी प्रोसेसर, गराज (Garage) से चंक सामग्री प्राप्त करता है:
|
||||
|
||||
```python
|
||||
# Get chunk_ids from embeddings store
|
||||
chunk_ids = await self.rag.doc_embeddings_client.query(...)
|
||||
|
||||
# Fetch chunk content from Garage
|
||||
docs = []
|
||||
for chunk_id in chunk_ids:
|
||||
content = await self.rag.librarian_client.get_document_content(
|
||||
chunk_id, self.user
|
||||
)
|
||||
docs.append(content)
|
||||
```
|
||||
|
||||
### एपीआई/एसडीके में बदलाव
|
||||
|
||||
**DocumentEmbeddingsClient** चंक_आईडी (chunk_ids) लौटाता है:
|
||||
```python
|
||||
return resp.chunk_ids # Changed from resp.chunks
|
||||
```
|
||||
|
||||
**वायर प्रारूप** (DocumentEmbeddingsResponseTranslator):
|
||||
```python
|
||||
result["chunk_ids"] = obj.chunk_ids # Changed from chunks
|
||||
```
|
||||
|
||||
### CLI में बदलाव
|
||||
|
||||
CLI टूल `chunk_ids` प्रदर्शित करता है (उपयोगकर्ता आवश्यकता पड़ने पर सामग्री को अलग से प्राप्त कर सकते हैं)।
|
||||
|
||||
## संशोधित करने योग्य फाइलें
|
||||
|
||||
### स्कीमा
|
||||
`trustgraph-base/trustgraph/schema/knowledge/embeddings.py` - `ChunkEmbeddings`
|
||||
`trustgraph-base/trustgraph/schema/services/query.py` - `DocumentEmbeddingsResponse`
|
||||
|
||||
### मैसेजिंग/अनुवादक
|
||||
`trustgraph-base/trustgraph/messaging/translators/embeddings_query.py` - `DocumentEmbeddingsResponseTranslator`
|
||||
|
||||
### क्लाइंट
|
||||
`trustgraph-base/trustgraph/base/document_embeddings_client.py` - `chunk_ids` लौटाएं
|
||||
|
||||
### पायथन SDK/API
|
||||
`trustgraph-base/trustgraph/api/flow.py` - `document_embeddings_query`
|
||||
`trustgraph-base/trustgraph/api/socket_client.py` - `document_embeddings_query`
|
||||
`trustgraph-base/trustgraph/api/async_flow.py` - यदि लागू हो
|
||||
`trustgraph-base/trustgraph/api/bulk_client.py` - दस्तावेज़ एम्बेडिंग का आयात/निर्यात
|
||||
`trustgraph-base/trustgraph/api/async_bulk_client.py` - दस्तावेज़ एम्बेडिंग का आयात/निर्यात
|
||||
|
||||
### एम्बेडिंग सेवा
|
||||
`trustgraph-flow/trustgraph/embeddings/document_embeddings/embeddings.py` - `chunk_id` पास करें
|
||||
|
||||
### स्टोरेज राइटर
|
||||
`trustgraph-flow/trustgraph/storage/doc_embeddings/qdrant/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/doc_embeddings/milvus/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/doc_embeddings/pinecone/write.py`
|
||||
|
||||
### क्वेरी सेवाएं
|
||||
`trustgraph-flow/trustgraph/query/doc_embeddings/qdrant/service.py`
|
||||
`trustgraph-flow/trustgraph/query/doc_embeddings/milvus/service.py`
|
||||
`trustgraph-flow/trustgraph/query/doc_embeddings/pinecone/service.py`
|
||||
|
||||
### गेटवे
|
||||
`trustgraph-flow/trustgraph/gateway/dispatch/document_embeddings_query.py`
|
||||
`trustgraph-flow/trustgraph/gateway/dispatch/document_embeddings_export.py`
|
||||
`trustgraph-flow/trustgraph/gateway/dispatch/document_embeddings_import.py`
|
||||
|
||||
### दस्तावेज़ RAG
|
||||
`trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` - लाइब्रेरियन क्लाइंट जोड़ें
|
||||
`trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` - गैरेज से प्राप्त करें
|
||||
|
||||
### CLI
|
||||
`trustgraph-cli/trustgraph/cli/invoke_document_embeddings.py`
|
||||
`trustgraph-cli/trustgraph/cli/save_doc_embeds.py`
|
||||
`trustgraph-cli/trustgraph/cli/load_doc_embeds.py`
|
||||
|
||||
## लाभ
|
||||
|
||||
1. सत्य का एकल स्रोत - केवल गैरेज में टेक्स्ट चंक
|
||||
2. वेक्टर स्टोर स्टोरेज में कमी
|
||||
3. `chunk_id` के माध्यम से क्वेरी-टाइम उत्पत्ति को सक्षम करता है
|
||||
675
docs/tech-specs/hi/embeddings-batch-processing.hi.md
Normal file
675
docs/tech-specs/hi/embeddings-batch-processing.hi.md
Normal file
|
|
@ -0,0 +1,675 @@
|
|||
---
|
||||
layout: default
|
||||
title: "एम्बेडिंग बैच प्रोसेसिंग तकनीकी विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# एम्बेडिंग बैच प्रोसेसिंग तकनीकी विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह विनिर्देश एम्बेडिंग सेवा के लिए अनुकूलन का वर्णन करता है ताकि एक ही अनुरोध में कई ग्रंथों को बैच में संसाधित किया जा सके। वर्तमान कार्यान्वयन एक समय में एक पाठ को संसाधित करता है, जिससे एम्बेडिंग मॉडल द्वारा प्रदान किए जाने वाले महत्वपूर्ण प्रदर्शन लाभों का उपयोग नहीं हो पाता है जब बैचों में प्रसंस्करण किया जाता है।
|
||||
|
||||
1. **सिंगल-टेक्स्ट प्रोसेसिंग की अक्षमता**: वर्तमान कार्यान्वयन एकल ग्रंथों को एक सूची में लपेटता है, जिससे FastEmbed की बैच क्षमताओं का पूरी तरह से उपयोग नहीं हो पाता है।
|
||||
2. **प्रति-टेक्स्ट अनुरोध ओवरहेड**: प्रत्येक पाठ के लिए एक अलग पल्सर संदेश राउंड-ट्रिप की आवश्यकता होती है।
|
||||
3. **मॉडल अनुमान की अक्षमता**: एम्बेडिंग मॉडल में एक निश्चित प्रति-बैच ओवरहेड होता है; छोटे बैच GPU/CPU संसाधनों को बर्बाद करते हैं।
|
||||
4. **कॉलरों में सीरियल प्रोसेसिंग**: प्रमुख सेवाएं आइटम्स पर लूप करती हैं और एक-एक करके एम्बेडिंग को कॉल करती हैं।
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
**बैच एपीआई समर्थन**: एक ही अनुरोध में कई ग्रंथों को संसाधित करने की क्षमता सक्षम करें।
|
||||
**पिछड़ा संगतता**: एकल-पाठ अनुरोधों के लिए समर्थन बनाए रखें।
|
||||
**महत्वपूर्ण थ्रूपुट सुधार**: बल्क ऑपरेशनों के लिए 5-10 गुना थ्रूपुट सुधार का लक्ष्य रखें।
|
||||
**प्रति-पाठ कम विलंबता**: कई ग्रंथों को एम्बेड करते समय औसत विलंबता को कम करें।
|
||||
**मेमोरी दक्षता**: अत्यधिक मेमोरी खपत के बिना बैचों को संसाधित करें।
|
||||
**प्रदाता-अज्ञेय**: FastEmbed, Ollama और अन्य प्रदाताओं में बैचिंग का समर्थन करें।
|
||||
**कॉलर माइग्रेशन**: सभी एम्बेडिंग कॉलरों को अपडेट करें ताकि वे जहां फायदेमंद हो वहां बैच एपीआई का उपयोग करें।
|
||||
|
||||
## पृष्ठभूमि
|
||||
|
||||
### वर्तमान कार्यान्वयन - एम्बेडिंग सेवा
|
||||
|
||||
`trustgraph-flow/trustgraph/embeddings/fastembed/processor.py` में एम्बेडिंग कार्यान्वयन में एक महत्वपूर्ण प्रदर्शन अक्षमता है:
|
||||
|
||||
```python
|
||||
# fastembed/processor.py line 56
|
||||
async def on_embeddings(self, text, model=None):
|
||||
use_model = model or self.default_model
|
||||
self._load_model(use_model)
|
||||
|
||||
vecs = self.embeddings.embed([text]) # Single text wrapped in list
|
||||
|
||||
return [v.tolist() for v in vecs]
|
||||
```
|
||||
|
||||
**समस्याएँ:**
|
||||
|
||||
1. **बैच का आकार 1**: FastEmbed का `embed()` तरीका बैच प्रोसेसिंग के लिए अनुकूलित है, लेकिन हम हमेशा इसे `[text]` के साथ कॉल करते हैं - जो कि आकार 1 का एक बैच है।
|
||||
|
||||
2. **प्रति-अनुरोध ओवरहेड**: प्रत्येक एम्बेडिंग अनुरोध में शामिल हैं:
|
||||
पल्सर संदेश का क्रमबद्धता/विघटन
|
||||
नेटवर्क राउंड-ट्रिप विलंबता
|
||||
मॉडल अनुमान स्टार्टअप ओवरहेड
|
||||
पायथन एसिंक्रोनस शेड्यूलिंग ओवरहेड
|
||||
|
||||
3. **स्कीमा सीमा**: `EmbeddingsRequest` स्कीमा केवल एक टेक्स्ट का समर्थन करता है:
|
||||
```python
|
||||
@dataclass
|
||||
class EmbeddingsRequest:
|
||||
text: str = "" # Single text only
|
||||
```
|
||||
|
||||
### वर्तमान कॉलर - सीरियल प्रोसेसिंग
|
||||
|
||||
#### 1. एपीआई गेटवे
|
||||
|
||||
**फ़ाइल:** `trustgraph-flow/trustgraph/gateway/dispatch/embeddings.py`
|
||||
|
||||
गेटवे HTTP/WebSocket के माध्यम से सिंगल-टेक्स्ट एम्बेडिंग अनुरोध स्वीकार करता है और उन्हें एम्बेडिंग सेवा को भेजता है। वर्तमान में कोई बैच एंडपॉइंट मौजूद नहीं है।
|
||||
|
||||
```python
|
||||
class EmbeddingsRequestor(ServiceRequestor):
|
||||
# Handles single EmbeddingsRequest -> EmbeddingsResponse
|
||||
request_schema=EmbeddingsRequest, # Single text only
|
||||
response_schema=EmbeddingsResponse,
|
||||
```
|
||||
|
||||
**प्रभाव:** बाहरी क्लाइंट (वेब ऐप्स, स्क्रिप्ट) को N टेक्स्ट एम्बेड करने के लिए N HTTP अनुरोध करने होंगे।
|
||||
|
||||
#### 2. दस्तावेज़ एम्बेडिंग सेवा
|
||||
|
||||
**फ़ाइल:** `trustgraph-flow/trustgraph/embeddings/document_embeddings/embeddings.py`
|
||||
|
||||
दस्तावेज़ के टुकड़ों को एक-एक करके संसाधित करता है:
|
||||
|
||||
```python
|
||||
async def on_message(self, msg, consumer, flow):
|
||||
v = msg.value()
|
||||
|
||||
# Single chunk per request
|
||||
resp = await flow("embeddings-request").request(
|
||||
EmbeddingsRequest(text=v.chunk)
|
||||
)
|
||||
vectors = resp.vectors
|
||||
```
|
||||
|
||||
**प्रभाव:** प्रत्येक दस्तावेज़ खंड के लिए एक अलग एम्बेडिंग कॉल की आवश्यकता होती है। 100 खंडों वाला एक दस्तावेज़ = 100 एम्बेडिंग अनुरोध।
|
||||
|
||||
#### 3. ग्राफ एम्बेडिंग सेवा
|
||||
|
||||
**फ़ाइल:** `trustgraph-flow/trustgraph/embeddings/graph_embeddings/embeddings.py`
|
||||
|
||||
यह एंटिटीज पर लूप करता है और प्रत्येक को क्रमिक रूप से एम्बेड करता है:
|
||||
|
||||
```python
|
||||
async def on_message(self, msg, consumer, flow):
|
||||
for entity in v.entities:
|
||||
# Serial embedding - one entity at a time
|
||||
vectors = await flow("embeddings-request").embed(
|
||||
text=entity.context
|
||||
)
|
||||
entities.append(EntityEmbeddings(
|
||||
entity=entity.entity,
|
||||
vectors=vectors,
|
||||
chunk_id=entity.chunk_id,
|
||||
))
|
||||
```
|
||||
|
||||
**प्रभाव:** 50 एंटिटीज वाला एक संदेश = 50 सीरियल एम्बेडिंग अनुरोध। यह ज्ञान ग्राफ निर्माण के दौरान एक बड़ी बाधा है।
|
||||
|
||||
#### 4. रो एम्बेडिंग सेवा
|
||||
|
||||
**फ़ाइल:** `trustgraph-flow/trustgraph/embeddings/row_embeddings/embeddings.py`
|
||||
|
||||
यह अद्वितीय टेक्स्ट पर लूप करता है और प्रत्येक को क्रमिक रूप से एम्बेड करता है:
|
||||
|
||||
```python
|
||||
async def on_message(self, msg, consumer, flow):
|
||||
for text, (index_name, index_value) in texts_to_embed.items():
|
||||
# Serial embedding - one text at a time
|
||||
vectors = await flow("embeddings-request").embed(text=text)
|
||||
|
||||
embeddings_list.append(RowIndexEmbedding(
|
||||
index_name=index_name,
|
||||
index_value=index_value,
|
||||
text=text,
|
||||
vectors=vectors
|
||||
))
|
||||
```
|
||||
|
||||
**प्रभाव:** 100 अद्वितीय अनुक्रमित मानों वाली तालिका को संसाधित करने से 100 सीरियल एम्बेडिंग अनुरोध उत्पन्न होते हैं।
|
||||
|
||||
#### 5. एम्बेडिंग्सक्लाइंट (बेस क्लाइंट)
|
||||
|
||||
**फ़ाइल:** `trustgraph-base/trustgraph/base/embeddings_client.py`
|
||||
|
||||
सभी फ्लो प्रोसेसर द्वारा उपयोग किए जाने वाले क्लाइंट केवल सिंगल-टेक्स्ट एम्बेडिंग का समर्थन करते हैं:
|
||||
|
||||
```python
|
||||
class EmbeddingsClient(RequestResponse):
|
||||
async def embed(self, text, timeout=30):
|
||||
resp = await self.request(
|
||||
EmbeddingsRequest(text=text), # Single text
|
||||
timeout=timeout
|
||||
)
|
||||
return resp.vectors
|
||||
```
|
||||
|
||||
**प्रभाव:** इस क्लाइंट का उपयोग करने वाले सभी एप्लिकेशन केवल एकल-पाठ संचालन तक सीमित हैं।
|
||||
|
||||
#### 6. कमांड-लाइन उपकरण
|
||||
|
||||
**फ़ाइल:** `trustgraph-cli/trustgraph/cli/invoke_embeddings.py`
|
||||
|
||||
कमांड-लाइन उपकरण एक एकल पाठ तर्क स्वीकार करता है:
|
||||
|
||||
```python
|
||||
def query(url, flow_id, text, token=None):
|
||||
result = flow.embeddings(text=text) # Single text
|
||||
vectors = result.get("vectors", [])
|
||||
```
|
||||
|
||||
**प्रभाव:** उपयोगकर्ता कमांड लाइन से बैच एम्बेडिंग नहीं कर सकते। टेक्स्ट फ़ाइल को संसाधित करने के लिए N बार कॉल की आवश्यकता होती है।
|
||||
|
||||
#### 7. पायथन SDK
|
||||
|
||||
पायथन SDK ट्रस्टग्राफ सेवाओं के साथ इंटरैक्ट करने के लिए दो क्लाइंट क्लास प्रदान करता है। दोनों केवल सिंगल-टेक्स्ट एम्बेडिंग का समर्थन करते हैं।
|
||||
|
||||
**फ़ाइल:** `trustgraph-base/trustgraph/api/flow.py`
|
||||
|
||||
```python
|
||||
class FlowInstance:
|
||||
def embeddings(self, text):
|
||||
"""Get embeddings for a single text"""
|
||||
input = {"text": text}
|
||||
return self.request("service/embeddings", input)["vectors"]
|
||||
```
|
||||
|
||||
**फ़ाइल:** `trustgraph-base/trustgraph/api/socket_client.py`
|
||||
|
||||
```python
|
||||
class SocketFlowInstance:
|
||||
def embeddings(self, text: str, **kwargs: Any) -> Dict[str, Any]:
|
||||
"""Get embeddings for a single text via WebSocket"""
|
||||
request = {"text": text}
|
||||
return self.client._send_request_sync(
|
||||
"embeddings", self.flow_id, request, False
|
||||
)
|
||||
```
|
||||
|
||||
**प्रभाव:** एसडीके का उपयोग करने वाले पायथन डेवलपर्स को टेक्स्ट पर लूप करना होगा और एन अलग एपीआई कॉल करने होंगे। एसडीके उपयोगकर्ताओं के लिए कोई बैच एम्बेडिंग समर्थन मौजूद नहीं है।
|
||||
|
||||
### प्रदर्शन प्रभाव
|
||||
|
||||
सामान्य दस्तावेज़ इनपुट (1000 टेक्स्ट खंड) के लिए:
|
||||
**वर्तमान:** 1000 अलग-अलग अनुरोध, 1000 मॉडल अनुमान कॉल
|
||||
**बैच (batch_size=32):** 32 अनुरोध, 32 मॉडल अनुमान कॉल (96.8% कमी)
|
||||
|
||||
ग्राफ एम्बेडिंग (50 संस्थाओं वाला संदेश) के लिए:
|
||||
**वर्तमान:** 50 सीरियल अवित कॉल, ~5-10 सेकंड
|
||||
**बैच:** 1-2 बैच कॉल, ~0.5-1 सेकंड (5-10 गुना सुधार)
|
||||
|
||||
FastEmbed और समान लाइब्रेरी हार्डवेयर सीमाओं तक बैच आकार के साथ लगभग रैखिक थ्रूपुट स्केलिंग प्राप्त करती हैं (आमतौर पर प्रति बैच 32-128 टेक्स्ट)।
|
||||
|
||||
## तकनीकी डिज़ाइन
|
||||
|
||||
### आर्किटेक्चर
|
||||
|
||||
एम्बेडिंग बैच प्रोसेसिंग अनुकूलन के लिए निम्नलिखित घटकों में परिवर्तन की आवश्यकता है:
|
||||
|
||||
#### 1. **स्कीमा संवर्धन**
|
||||
`EmbeddingsRequest` को कई टेक्स्ट का समर्थन करने के लिए विस्तारित करें
|
||||
`EmbeddingsResponse` को कई वेक्टर सेट वापस करने के लिए विस्तारित करें
|
||||
एकल-टेक्स्ट अनुरोधों के साथ पिछड़े अनुकूलता बनाए रखें
|
||||
|
||||
मॉड्यूल: `trustgraph-base/trustgraph/schema/services/llm.py`
|
||||
|
||||
#### 2. **बेस सर्विस संवर्धन**
|
||||
`EmbeddingsService` को बैच अनुरोधों को संभालने के लिए अपडेट करें
|
||||
बैच आकार कॉन्फ़िगरेशन जोड़ें
|
||||
बैच-जागरूक अनुरोध हैंडलिंग लागू करें
|
||||
|
||||
मॉड्यूल: `trustgraph-base/trustgraph/base/embeddings_service.py`
|
||||
|
||||
#### 3. **प्रदाता प्रोसेसर अपडेट**
|
||||
FastEmbed प्रोसेसर को अपडेट करें ताकि `embed()` को पूरा बैच पास किया जा सके
|
||||
यदि समर्थित है, तो बैचों को संभालने के लिए Ollama प्रोसेसर को अपडेट करें
|
||||
बैच समर्थन के बिना प्रदाताओं के लिए एक वैकल्पिक अनुक्रमिक प्रसंस्करण जोड़ें
|
||||
|
||||
मॉड्यूल:
|
||||
`trustgraph-flow/trustgraph/embeddings/fastembed/processor.py`
|
||||
`trustgraph-flow/trustgraph/embeddings/ollama/processor.py`
|
||||
|
||||
#### 4. **क्लाइंट में सुधार**
|
||||
`EmbeddingsClient` में बैच एम्बेडिंग विधि जोड़ें
|
||||
सिंगल और बैच एपीआई दोनों का समर्थन करें
|
||||
बड़े इनपुट के लिए स्वचालित बैचिंग जोड़ें
|
||||
|
||||
मॉड्यूल: `trustgraph-base/trustgraph/base/embeddings_client.py`
|
||||
|
||||
#### 5. **कॉल करने वाले अपडेट - फ्लो प्रोसेसर**
|
||||
`graph_embeddings` को बैच एंटिटी कॉन्टेक्स्ट के लिए अपडेट करें
|
||||
`row_embeddings` को बैच इंडेक्स टेक्स्ट के लिए अपडेट करें
|
||||
यदि संदेश बैचिंग संभव है, तो `document_embeddings` को अपडेट करें
|
||||
|
||||
मॉड्यूल:
|
||||
`trustgraph-flow/trustgraph/embeddings/graph_embeddings/embeddings.py`
|
||||
`trustgraph-flow/trustgraph/embeddings/row_embeddings/embeddings.py`
|
||||
`trustgraph-flow/trustgraph/embeddings/document_embeddings/embeddings.py`
|
||||
|
||||
#### 6. **एपीआई गेटवे में सुधार**
|
||||
बैच एम्बेडिंग एंडपॉइंट जोड़ें
|
||||
अनुरोध बॉडी में टेक्स्ट की सरणी का समर्थन करें
|
||||
|
||||
मॉड्यूल: `trustgraph-flow/trustgraph/gateway/dispatch/embeddings.py`
|
||||
|
||||
#### 7. **सीएलआई टूल में सुधार**
|
||||
कई टेक्स्ट या फ़ाइल इनपुट के लिए समर्थन जोड़ें
|
||||
बैच आकार पैरामीटर जोड़ें
|
||||
|
||||
मॉड्यूल: `trustgraph-cli/trustgraph/cli/invoke_embeddings.py`
|
||||
|
||||
#### 8. **पायथन एसडीके में सुधार**
|
||||
`FlowInstance` में `embeddings_batch()` विधि जोड़ें
|
||||
`SocketFlowInstance` में `embeddings_batch()` विधि जोड़ें
|
||||
एसडीके उपयोगकर्ताओं के लिए सिंगल और बैच एपीआई दोनों का समर्थन करें
|
||||
|
||||
मॉड्यूल:
|
||||
`trustgraph-base/trustgraph/api/flow.py`
|
||||
`trustgraph-base/trustgraph/api/socket_client.py`
|
||||
|
||||
### डेटा मॉडल
|
||||
|
||||
#### एम्बेडिंग्स रिक्वेस्ट
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class EmbeddingsRequest:
|
||||
texts: list[str] = field(default_factory=list)
|
||||
```
|
||||
|
||||
उपयोग:
|
||||
एकल पाठ: `EmbeddingsRequest(texts=["hello world"])`
|
||||
बैच: `EmbeddingsRequest(texts=["text1", "text2", "text3"])`
|
||||
|
||||
#### एम्बेडिंग रिस्पांस
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class EmbeddingsResponse:
|
||||
error: Error | None = None
|
||||
vectors: list[list[list[float]]] = field(default_factory=list)
|
||||
```
|
||||
|
||||
प्रतिक्रिया संरचना:
|
||||
`vectors[i]` में `texts[i]` के लिए वेक्टर सेट शामिल है।
|
||||
प्रत्येक वेक्टर सेट `list[list[float]]` होता है (मॉडल प्रत्येक पाठ के लिए कई वेक्टर वापस कर सकते हैं)।
|
||||
उदाहरण: 3 पाठ → `vectors` में 3 प्रविष्टियाँ हैं, जिनमें से प्रत्येक में उस पाठ के एम्बेडिंग होते हैं।
|
||||
|
||||
### एपीआई
|
||||
|
||||
#### एम्बेडिंगक्लाइंट
|
||||
|
||||
```python
|
||||
class EmbeddingsClient(RequestResponse):
|
||||
async def embed(
|
||||
self,
|
||||
texts: list[str],
|
||||
timeout: float = 300,
|
||||
) -> list[list[list[float]]]:
|
||||
"""
|
||||
Embed one or more texts in a single request.
|
||||
|
||||
Args:
|
||||
texts: List of texts to embed
|
||||
timeout: Timeout for the operation
|
||||
|
||||
Returns:
|
||||
List of vector sets, one per input text
|
||||
"""
|
||||
resp = await self.request(
|
||||
EmbeddingsRequest(texts=texts),
|
||||
timeout=timeout
|
||||
)
|
||||
if resp.error:
|
||||
raise RuntimeError(resp.error.message)
|
||||
return resp.vectors
|
||||
```
|
||||
|
||||
#### एपीआई गेटवे एम्बेडिंग एंडपॉइंट
|
||||
|
||||
अपडेटेड एंडपॉइंट जो सिंगल या बैच एम्बेडिंग को सपोर्ट करता है:
|
||||
|
||||
```
|
||||
POST /api/v1/embeddings
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"texts": ["text1", "text2", "text3"],
|
||||
"flow_id": "default"
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"vectors": [
|
||||
[[0.1, 0.2, ...]],
|
||||
[[0.3, 0.4, ...]],
|
||||
[[0.5, 0.6, ...]]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### कार्यान्वयन विवरण
|
||||
|
||||
#### चरण 1: स्कीमा परिवर्तन
|
||||
|
||||
**एम्बेडिंग रिक्वेस्ट:**
|
||||
```python
|
||||
@dataclass
|
||||
class EmbeddingsRequest:
|
||||
texts: list[str] = field(default_factory=list)
|
||||
```
|
||||
|
||||
**एम्बेडिंग रिस्पांस:**
|
||||
```python
|
||||
@dataclass
|
||||
class EmbeddingsResponse:
|
||||
error: Error | None = None
|
||||
vectors: list[list[list[float]]] = field(default_factory=list)
|
||||
```
|
||||
|
||||
**अपडेटेड एम्बेडिंगसर्विस.ऑन_रिक्वेस्ट:**
|
||||
```python
|
||||
async def on_request(self, msg, consumer, flow):
|
||||
request = msg.value()
|
||||
id = msg.properties()["id"]
|
||||
model = flow("model")
|
||||
|
||||
vectors = await self.on_embeddings(request.texts, model=model)
|
||||
response = EmbeddingsResponse(error=None, vectors=vectors)
|
||||
|
||||
await flow("response").send(response, properties={"id": id})
|
||||
```
|
||||
|
||||
#### चरण 2: फास्टएम्बेड प्रोसेसर अपडेट
|
||||
|
||||
**वर्तमान (अकुशल):**
|
||||
```python
|
||||
async def on_embeddings(self, text, model=None):
|
||||
use_model = model or self.default_model
|
||||
self._load_model(use_model)
|
||||
vecs = self.embeddings.embed([text]) # Batch of 1
|
||||
return [v.tolist() for v in vecs]
|
||||
```
|
||||
|
||||
**अद्यतन:**
|
||||
```python
|
||||
async def on_embeddings(self, texts: list[str], model=None):
|
||||
"""Embed texts - processes all texts in single model call"""
|
||||
if not texts:
|
||||
return []
|
||||
|
||||
use_model = model or self.default_model
|
||||
self._load_model(use_model)
|
||||
|
||||
# FastEmbed handles the full batch efficiently
|
||||
all_vecs = list(self.embeddings.embed(texts))
|
||||
|
||||
# Return list of vector sets, one per input text
|
||||
return [[v.tolist()] for v in all_vecs]
|
||||
```
|
||||
|
||||
#### चरण 3: ग्राफ एम्बेडिंग सेवा अपडेट
|
||||
|
||||
**वर्तमान (सीरियल):**
|
||||
```python
|
||||
async def on_message(self, msg, consumer, flow):
|
||||
entities = []
|
||||
for entity in v.entities:
|
||||
vectors = await flow("embeddings-request").embed(text=entity.context)
|
||||
entities.append(EntityEmbeddings(...))
|
||||
```
|
||||
|
||||
**अद्यतन (बैच):**
|
||||
```python
|
||||
async def on_message(self, msg, consumer, flow):
|
||||
# Collect all contexts
|
||||
contexts = [entity.context for entity in v.entities]
|
||||
|
||||
# Single batch embedding call
|
||||
all_vectors = await flow("embeddings-request").embed(texts=contexts)
|
||||
|
||||
# Pair results with entities
|
||||
entities = [
|
||||
EntityEmbeddings(
|
||||
entity=entity.entity,
|
||||
vectors=vectors[0], # First vector from the set
|
||||
chunk_id=entity.chunk_id,
|
||||
)
|
||||
for entity, vectors in zip(v.entities, all_vectors)
|
||||
]
|
||||
```
|
||||
|
||||
#### चरण 4: पंक्ति एम्बेडिंग सेवा अपडेट
|
||||
|
||||
**वर्तमान (क्रमिक):**
|
||||
```python
|
||||
for text, (index_name, index_value) in texts_to_embed.items():
|
||||
vectors = await flow("embeddings-request").embed(text=text)
|
||||
embeddings_list.append(RowIndexEmbedding(...))
|
||||
```
|
||||
|
||||
**अद्यतन (बैच):**
|
||||
```python
|
||||
# Collect texts and metadata
|
||||
texts = list(texts_to_embed.keys())
|
||||
metadata = list(texts_to_embed.values())
|
||||
|
||||
# Single batch embedding call
|
||||
all_vectors = await flow("embeddings-request").embed(texts=texts)
|
||||
|
||||
# Pair results
|
||||
embeddings_list = [
|
||||
RowIndexEmbedding(
|
||||
index_name=meta[0],
|
||||
index_value=meta[1],
|
||||
text=text,
|
||||
vectors=vectors[0] # First vector from the set
|
||||
)
|
||||
for text, meta, vectors in zip(texts, metadata, all_vectors)
|
||||
]
|
||||
```
|
||||
|
||||
#### चरण 5: कमांड-लाइन टूल में सुधार
|
||||
|
||||
**अद्यतन कमांड-लाइन इंटरफ़ेस:**
|
||||
```python
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(...)
|
||||
|
||||
parser.add_argument(
|
||||
'text',
|
||||
nargs='*', # Zero or more texts
|
||||
help='Text(s) to convert to embedding vectors',
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'-f', '--file',
|
||||
help='File containing texts (one per line)',
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--batch-size',
|
||||
type=int,
|
||||
default=32,
|
||||
help='Batch size for processing (default: 32)',
|
||||
)
|
||||
```
|
||||
|
||||
उपयोग:
|
||||
```bash
|
||||
# Single text (existing)
|
||||
tg-invoke-embeddings "hello world"
|
||||
|
||||
# Multiple texts
|
||||
tg-invoke-embeddings "text one" "text two" "text three"
|
||||
|
||||
# From file
|
||||
tg-invoke-embeddings -f texts.txt --batch-size 64
|
||||
```
|
||||
|
||||
#### चरण 6: पायथन एसडीके में सुधार
|
||||
|
||||
**फ्लोइंस्टेंस (एचटीटीपी क्लाइंट):**
|
||||
|
||||
```python
|
||||
class FlowInstance:
|
||||
def embeddings(self, texts: list[str]) -> list[list[list[float]]]:
|
||||
"""
|
||||
Get embeddings for one or more texts.
|
||||
|
||||
Args:
|
||||
texts: List of texts to embed
|
||||
|
||||
Returns:
|
||||
List of vector sets, one per input text
|
||||
"""
|
||||
input = {"texts": texts}
|
||||
return self.request("service/embeddings", input)["vectors"]
|
||||
```
|
||||
|
||||
**सॉकेटफ्लोइंस्टेंस (वेबसोकेट क्लाइंट):**
|
||||
|
||||
```python
|
||||
class SocketFlowInstance:
|
||||
def embeddings(self, texts: list[str], **kwargs: Any) -> list[list[list[float]]]:
|
||||
"""
|
||||
Get embeddings for one or more texts via WebSocket.
|
||||
|
||||
Args:
|
||||
texts: List of texts to embed
|
||||
|
||||
Returns:
|
||||
List of vector sets, one per input text
|
||||
"""
|
||||
request = {"texts": texts}
|
||||
response = self.client._send_request_sync(
|
||||
"embeddings", self.flow_id, request, False
|
||||
)
|
||||
return response["vectors"]
|
||||
```
|
||||
|
||||
**एसडीके उपयोग के उदाहरण:**
|
||||
|
||||
```python
|
||||
# Single text
|
||||
vectors = flow.embeddings(["hello world"])
|
||||
print(f"Dimensions: {len(vectors[0][0])}")
|
||||
|
||||
# Batch embedding
|
||||
texts = ["text one", "text two", "text three"]
|
||||
all_vectors = flow.embeddings(texts)
|
||||
|
||||
# Process results
|
||||
for text, vecs in zip(texts, all_vectors):
|
||||
print(f"{text}: {len(vecs[0])} dimensions")
|
||||
```
|
||||
|
||||
## सुरक्षा संबंधी विचार
|
||||
|
||||
**अनुरोध आकार सीमाएँ**: संसाधनों की कमी को रोकने के लिए अधिकतम बैच आकार लागू करें।
|
||||
**समय-सीमा प्रबंधन**: बैच आकार के लिए समय-सीमा को उचित रूप से समायोजित करें।
|
||||
**मेमोरी सीमाएँ**: बड़े बैचों के लिए मेमोरी उपयोग की निगरानी करें।
|
||||
**इनपुट सत्यापन**: प्रसंस्करण से पहले बैच में सभी पाठों को मान्य करें।
|
||||
|
||||
## प्रदर्शन संबंधी विचार
|
||||
|
||||
### अपेक्षित सुधार
|
||||
|
||||
**थ्रूपुट:**
|
||||
एकल-पाठ: ~10-50 पाठ/सेकंड (मॉडल के आधार पर)
|
||||
बैच (आकार 32): ~200-500 पाठ/सेकंड (5-10 गुना सुधार)
|
||||
|
||||
**प्रति पाठ विलंबता:**
|
||||
एकल-पाठ: प्रति पाठ 50-200ms
|
||||
बैच (आकार 32): प्रति पाठ 5-20ms (औसत)
|
||||
|
||||
**सेवा-विशिष्ट सुधार:**
|
||||
|
||||
| सेवा | वर्तमान | बैच | सुधार |
|
||||
|---------|---------|---------|-------------|
|
||||
| ग्राफ एम्बेडिंग (50 इकाइयाँ) | 5-10s | 0.5-1s | 5-10x |
|
||||
| पंक्ति एम्बेडिंग (100 पाठ) | 10-20s | 1-2s | 5-10x |
|
||||
| दस्तावेज़ इनपुट (1000 खंड) | 100-200s | 10-30s | 5-10x |
|
||||
|
||||
### कॉन्फ़िगरेशन पैरामीटर
|
||||
|
||||
```python
|
||||
# Recommended defaults
|
||||
DEFAULT_BATCH_SIZE = 32
|
||||
MAX_BATCH_SIZE = 128
|
||||
BATCH_TIMEOUT_MULTIPLIER = 2.0
|
||||
```
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
### यूनिट परीक्षण
|
||||
सिंगल टेक्स्ट एम्बेडिंग (पिछड़ा संगतता)
|
||||
खाली बैच हैंडलिंग
|
||||
अधिकतम बैच आकार का प्रवर्तन
|
||||
आंशिक बैच विफलताओं के लिए त्रुटि हैंडलिंग
|
||||
|
||||
### एकीकरण परीक्षण
|
||||
पल्सर के माध्यम से एंड-टू-एंड बैच एम्बेडिंग
|
||||
ग्राफ एम्बेडिंग सेवा बैच प्रसंस्करण
|
||||
रो एम्बेडिंग सेवा बैच प्रसंस्करण
|
||||
एपीआई गेटवे बैच एंडपॉइंट
|
||||
|
||||
### प्रदर्शन परीक्षण
|
||||
सिंगल बनाम बैच थ्रूपुट का बेंचमार्क
|
||||
विभिन्न बैच आकारों के तहत मेमोरी उपयोग
|
||||
विलंबता वितरण विश्लेषण
|
||||
|
||||
## माइग्रेशन योजना
|
||||
|
||||
यह एक ब्रेकिंग चेंज रिलीज़ है। सभी चरण एक साथ लागू किए गए हैं।
|
||||
|
||||
### चरण 1: स्कीमा परिवर्तन
|
||||
EmbeddingsRequest में `text: str` को `texts: list[str]` से बदलें
|
||||
EmbeddingsResponse में `vectors` प्रकार को `list[list[list[float]]]` में बदलें
|
||||
|
||||
### चरण 2: प्रोसेसर अपडेट
|
||||
FastEmbed और Ollama प्रोसेसर में `on_embeddings` हस्ताक्षर को अपडेट करें
|
||||
सिंगल मॉडल कॉल में पूरा बैच संसाधित करें
|
||||
|
||||
### चरण 3: क्लाइंट अपडेट
|
||||
`EmbeddingsClient.embed()` को `texts: list[str]` स्वीकार करने के लिए अपडेट करें
|
||||
|
||||
### चरण 4: कॉलर अपडेट
|
||||
graph_embeddings को बैच एंटिटी संदर्भों के लिए अपडेट करें
|
||||
row_embeddings को बैच इंडेक्स टेक्स्ट के लिए अपडेट करें
|
||||
document_embeddings को नए स्कीमा का उपयोग करने के लिए अपडेट करें
|
||||
CLI टूल को अपडेट करें
|
||||
|
||||
### चरण 5: एपीआई गेटवे
|
||||
नए स्कीमा के लिए एम्बेडिंग एंडपॉइंट को अपडेट करें
|
||||
|
||||
### चरण 6: पायथन SDK
|
||||
`FlowInstance.embeddings()` हस्ताक्षर को अपडेट करें
|
||||
`SocketFlowInstance.embeddings()` हस्ताक्षर को अपडेट करें
|
||||
|
||||
## खुले प्रश्न
|
||||
|
||||
**बड़े बैचों का स्ट्रीमिंग**: क्या हमें बहुत बड़े बैचों (>100 टेक्स्ट) के लिए स्ट्रीमिंग परिणामों का समर्थन करना चाहिए?
|
||||
**प्रदाता-विशिष्ट सीमाएँ**: हमें विभिन्न अधिकतम बैच आकारों वाले प्रदाताओं को कैसे संभालना चाहिए?
|
||||
**आंशिक विफलता हैंडलिंग**: यदि बैच में एक टेक्स्ट विफल हो जाता है, तो क्या हमें पूरे बैच को विफल करना चाहिए या आंशिक परिणाम लौटाने चाहिए?
|
||||
**डॉक्यूमेंट एम्बेडिंग बैचिंग**: क्या हमें कई चंक संदेशों में बैच करना चाहिए या प्रति-संदेश प्रसंस्करण बनाए रखना चाहिए?
|
||||
|
||||
## संदर्भ
|
||||
|
||||
[FastEmbed Documentation](https://github.com/qdrant/fastembed)
|
||||
[Ollama Embeddings API](https://github.com/ollama/ollama)
|
||||
[EmbeddingsService Implementation](trustgraph-base/trustgraph/base/embeddings_service.py)
|
||||
[GraphRAG Performance Optimization](graphrag-performance-optimization.md)
|
||||
268
docs/tech-specs/hi/entity-centric-graph.hi.md
Normal file
268
docs/tech-specs/hi/entity-centric-graph.hi.md
Normal file
|
|
@ -0,0 +1,268 @@
|
|||
---
|
||||
layout: default
|
||||
title: "एंटिटी-सेंट्रिक नॉलेज ग्राफ स्टोरेज ऑन कैसेंड्रा"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# एंटिटी-सेंट्रिक नॉलेज ग्राफ स्टोरेज ऑन कैसेंड्रा
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह दस्तावेज़ अपाचे कैसेंड्रा पर आरडीएफ-शैली नॉलेज ग्राफ के लिए एक स्टोरेज मॉडल का वर्णन करता है। यह मॉडल एक **एंटिटी-सेंट्रिक** दृष्टिकोण का उपयोग करता है, जिसमें प्रत्येक एंटिटी उन सभी क्वाड के बारे में जानती है जिनमें वह भाग लेता है और वह जो भूमिका निभाता है। यह पारंपरिक मल्टी-टेबल एस.पी.ओ. क्रमपरिवर्तन दृष्टिकोण को केवल दो तालिकाओं से बदल देता है।
|
||||
|
||||
## पृष्ठभूमि और प्रेरणा
|
||||
|
||||
### पारंपरिक दृष्टिकोण
|
||||
|
||||
कैसेंड्रा पर एक मानक आरडीएफ क्वाड स्टोर को क्वेरी पैटर्न को कवर करने के लिए कई डीनॉर्मलाइज़्ड तालिकाओं की आवश्यकता होती है - आमतौर पर 6 या अधिक टेबल जो विषय, विधेय, वस्तु और डेटासेट (एसपीओडी) के विभिन्न क्रमपरिवर्तनों का प्रतिनिधित्व करते हैं। प्रत्येक क्वाड को प्रत्येक तालिका में लिखा जाता है, जिसके परिणामस्वरूप महत्वपूर्ण राइट एम्प्लीफिकेशन, परिचालन ओवरहेड और स्कीमा जटिलता होती है।
|
||||
|
||||
इसके अतिरिक्त, लेबल रिज़ॉल्यूशन (एंटिटीज के लिए मानव-पठनीय नामों को प्राप्त करना) के लिए अलग राउंड-ट्रिप क्वेरी की आवश्यकता होती है, जो एआई और ग्राफआरएजी उपयोग के मामलों में विशेष रूप से महंगी होती है, जहां एलएलएम संदर्भ के लिए लेबल आवश्यक हैं।
|
||||
|
||||
### एंटिटी-सेंट्रिक अंतर्दृष्टि
|
||||
|
||||
प्रत्येक क्वाड `(D, S, P, O)` में अधिकतम 4 एंटिटीज शामिल होती हैं। प्रत्येक एंटिटी की क्वाड में भागीदारी के लिए एक पंक्ति लिखकर, हम यह गारंटी देते हैं कि **किसी भी क्वेरी में कम से कम एक ज्ञात तत्व होगा, जो एक विभाजन कुंजी पर हिट करेगा।** यह एकल डेटा तालिका के साथ सभी 16 क्वेरी पैटर्न को कवर करता है।
|
||||
|
||||
मुख्य लाभ:
|
||||
|
||||
**2 टेबल** 7+ तालिकाओं के बजाय
|
||||
**प्रति क्वाड 4 राइट** 6+ राइट के बजाय
|
||||
**लेबल रिज़ॉल्यूशन मुफ्त में** - एक एंटिटी के लेबल उसके संबंधों के साथ स्थित होते हैं, जो स्वाभाविक रूप से एप्लिकेशन कैश को गर्म करते हैं
|
||||
**सभी 16 क्वेरी पैटर्न** सिंगल-पार्टिशन रीड द्वारा परोसे जाते हैं
|
||||
**सरल संचालन** - ट्यून करने, कंपैक्ट करने और रिपेयर करने के लिए एक डेटा टेबल
|
||||
|
||||
## स्कीमा
|
||||
|
||||
### टेबल 1: quads_by_entity
|
||||
|
||||
प्राथमिक डेटा तालिका। प्रत्येक एंटिटी में एक विभाजन होता है जिसमें वह सभी क्वाड शामिल होते हैं जिनमें वह भाग लेता है। क्वेरी पैटर्न (एंटिटी द्वारा लुकअप) को दर्शाने के लिए नामित।
|
||||
|
||||
```sql
|
||||
CREATE TABLE quads_by_entity (
|
||||
collection text, -- Collection/tenant scope (always specified)
|
||||
entity text, -- The entity this row is about
|
||||
role text, -- 'S', 'P', 'O', 'G' — how this entity participates
|
||||
p text, -- Predicate of the quad
|
||||
otype text, -- 'U' (URI), 'L' (literal), 'T' (triple/reification)
|
||||
s text, -- Subject of the quad
|
||||
o text, -- Object of the quad
|
||||
d text, -- Dataset/graph of the quad
|
||||
dtype text, -- XSD datatype (when otype = 'L'), e.g. 'xsd:string'
|
||||
lang text, -- Language tag (when otype = 'L'), e.g. 'en', 'fr'
|
||||
PRIMARY KEY ((collection, entity), role, p, otype, s, o, d, dtype, lang)
|
||||
);
|
||||
```
|
||||
|
||||
**विभाजन कुंजी (पार्टिशन की):** `(collection, entity)` — संग्रह के लिए निर्धारित, प्रत्येक इकाई के लिए एक विभाजन।
|
||||
|
||||
**क्लस्टरिंग कॉलम क्रम का तर्क:**
|
||||
|
||||
1. **भूमिका (role):** अधिकांश क्वेरी "यह इकाई विषय/वस्तु है" से शुरू होती हैं।
|
||||
2. **p:** अगला सबसे आम फ़िल्टर, "मुझे सभी `knows` संबंध दिखाएं"।
|
||||
3. **otype:** URI-मान वाले बनाम शाब्दिक-मान वाले संबंधों के आधार पर फ़िल्टर करने में सक्षम बनाता है।
|
||||
4. **s, o, d:** विशिष्टता के लिए शेष कॉलम।
|
||||
5. **dtype, lang:** समान मान वाले लेकिन अलग-अलग प्रकार के मेटाडेटा वाले शाब्दिकों को अलग करने के लिए (उदाहरण के लिए, `"thing"` बनाम `"thing"@en` बनाम `"thing"^^xsd:string`)।
|
||||
|
||||
### तालिका 2: quads_by_collection
|
||||
|
||||
संग्रह-स्तरीय क्वेरी और हटाने का समर्थन करता है। यह एक संग्रह से संबंधित सभी क्वाड का एक विवरण प्रदान करता है। इसे उस क्वेरी पैटर्न को दर्शाने के लिए नामित किया गया है (संग्रह द्वारा खोज)।
|
||||
|
||||
```sql
|
||||
CREATE TABLE quads_by_collection (
|
||||
collection text,
|
||||
d text, -- Dataset/graph of the quad
|
||||
s text, -- Subject of the quad
|
||||
p text, -- Predicate of the quad
|
||||
o text, -- Object of the quad
|
||||
otype text, -- 'U' (URI), 'L' (literal), 'T' (triple/reification)
|
||||
dtype text, -- XSD datatype (when otype = 'L')
|
||||
lang text, -- Language tag (when otype = 'L')
|
||||
PRIMARY KEY (collection, d, s, p, o, otype, dtype, lang)
|
||||
);
|
||||
```
|
||||
|
||||
सबसे पहले डेटासेट के आधार पर समूहीकृत किया जाता है, जिससे संग्रह या डेटासेट स्तर पर हटाने की सुविधा मिलती है। `otype`, `dtype`, और `lang` कॉलम को समूहीकरण कुंजी में शामिल किया गया है ताकि समान मान वाले लिटरल को अलग किया जा सके, लेकिन अलग-अलग प्रकार के मेटाडेटा के साथ - RDF में, `"thing"`, `"thing"@en`, और `"thing"^^xsd:string` अर्थपूर्ण रूप से भिन्न मान हैं।
|
||||
|
||||
## लेखन पथ
|
||||
|
||||
प्रत्येक आने वाले क्वाड `(D, S, P, O)` के लिए, जो संग्रह `C` के भीतर है, `quads_by_entity` में **4 पंक्तियाँ** और `quads_by_collection` में **1 पंक्ति** लिखें।
|
||||
|
||||
### उदाहरण
|
||||
|
||||
संग्रह `tenant1` में क्वाड दिया गया है:
|
||||
|
||||
```
|
||||
Dataset: https://example.org/graph1
|
||||
Subject: https://example.org/Alice
|
||||
Predicate: https://example.org/knows
|
||||
Object: https://example.org/Bob
|
||||
```
|
||||
|
||||
`quads_by_entity` में 4 पंक्तियाँ लिखें:
|
||||
|
||||
| संग्रह | इकाई | भूमिका | p | otype | s | o | d |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| tenant1 | https://example.org/graph1 | G | https://example.org/knows | U | https://example.org/Alice | https://example.org/Bob | https://example.org/graph1 |
|
||||
| tenant1 | https://example.org/Alice | S | https://example.org/knows | U | https://example.org/Alice | https://example.org/Bob | https://example.org/graph1 |
|
||||
| tenant1 | https://example.org/knows | P | https://example.org/knows | U | https://example.org/Alice | https://example.org/Bob | https://example.org/graph1 |
|
||||
| tenant1 | https://example.org/Bob | O | https://example.org/knows | U | https://example.org/Alice | https://example.org/Bob | https://example.org/graph1 |
|
||||
|
||||
`quads_by_collection` में 1 पंक्ति लिखें:
|
||||
|
||||
| संग्रह | d | s | p | o | otype | dtype | lang |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| tenant1 | https://example.org/graph1 | https://example.org/Alice | https://example.org/knows | https://example.org/Bob | U | | |
|
||||
|
||||
### शाब्दिक उदाहरण
|
||||
|
||||
एक लेबल ट्रिपल के लिए:
|
||||
|
||||
```
|
||||
Dataset: https://example.org/graph1
|
||||
Subject: https://example.org/Alice
|
||||
Predicate: http://www.w3.org/2000/01/rdf-schema#label
|
||||
Object: "Alice Smith" (lang: en)
|
||||
```
|
||||
|
||||
`otype` का मान `'L'` है, `dtype` का मान `'xsd:string'` है, और `lang` का मान `'en'` है। शाब्दिक मान `"Alice Smith"` को `o` में संग्रहीत किया जाता है। `quads_by_entity` में केवल 3 पंक्तियों की आवश्यकता होती है - शाब्दिक को इकाई के रूप में लिखने के लिए कोई पंक्ति नहीं लिखी जाती है, क्योंकि शाब्दिक स्वतंत्र रूप से क्वेरी करने योग्य इकाइयाँ नहीं हैं।
|
||||
|
||||
## क्वेरी पैटर्न
|
||||
|
||||
### सभी 16 डीएसपीओ पैटर्न
|
||||
|
||||
नीचे दी गई तालिका में, "परिपूर्ण उपसर्ग" का अर्थ है कि क्वेरी क्लस्टरिंग कॉलम के एक निरंतर उपसर्ग का उपयोग करती है। "विभाजन स्कैन + फ़िल्टर" का अर्थ है कि कैसेंड्रा एक विभाजन के एक स्लाइस को पढ़ता है और मेमोरी में फ़िल्टर करता है - यह कुशल है, लेकिन यह एक शुद्ध उपसर्ग मिलान नहीं है।
|
||||
|
||||
| # | ज्ञात | लुकअप इकाई | क्लस्टरिंग उपसर्ग | दक्षता |
|
||||
|---|---|---|---|---|
|
||||
| 1 | डी, एस, पी, ओ | इकाई=एस, भूमिका='एस', पी=पी | पूर्ण मिलान | परिपूर्ण उपसर्ग |
|
||||
| 2 | डी, एस, पी, ? | इकाई=एस, भूमिका='एस', पी=पी | डी पर फ़िल्टर | विभाजन स्कैन + फ़िल्टर |
|
||||
| 3 | डी, एस, ?, ओ | इकाई=एस, भूमिका='एस' | डी, ओ पर फ़िल्टर | विभाजन स्कैन + फ़िल्टर |
|
||||
| 4 | डी, ?, पी, ओ | इकाई=ओ, भूमिका='ओ', पी=पी | डी पर फ़िल्टर | विभाजन स्कैन + फ़िल्टर |
|
||||
| 5 | ?, एस, पी, ओ | इकाई=एस, भूमिका='एस', पी=पी | ओ पर फ़िल्टर | विभाजन स्कैन + फ़िल्टर |
|
||||
| 6 | डी, एस, ?, ? | इकाई=एस, भूमिका='एस' | डी पर फ़िल्टर | विभाजन स्कैन + फ़िल्टर |
|
||||
| 7 | डी, ?, पी, ? | इकाई=पी, भूमिका='पी' | डी पर फ़िल्टर | विभाजन स्कैन + फ़िल्टर |
|
||||
| 8 | डी, ?, ?, ओ | इकाई=ओ, भूमिका='ओ' | डी पर फ़िल्टर | विभाजन स्कैन + फ़िल्टर |
|
||||
| 9 | ?, एस, पी, ? | इकाई=एस, भूमिका='एस', पी=पी | — | **परिपूर्ण उपसर्ग** |
|
||||
| 10 | ?, एस, ?, ओ | इकाई=एस, भूमिका='एस' | ओ पर फ़िल्टर | विभाजन स्कैन + फ़िल्टर |
|
||||
| 11 | ?, ?, पी, ओ | इकाई=ओ, भूमिका='ओ', पी=पी | — | **परिपूर्ण उपसर्ग** |
|
||||
| 12 | डी, ?, ?, ? | इकाई=डी, भूमिका='जी' | — | **परिपूर्ण उपसर्ग** |
|
||||
| 13 | ?, एस, ?, ? | इकाई=एस, भूमिका='एस' | — | **परिपूर्ण उपसर्ग** |
|
||||
| 14 | ?, ?, पी, ? | इकाई=पी, भूमिका='पी' | — | **परिपूर्ण उपसर्ग** |
|
||||
| 15 | ?, ?, ?, ओ | इकाई=ओ, भूमिका='ओ' | — | **परिपूर्ण उपसर्ग** |
|
||||
| 16 | ?, ?, ?, ? | — | पूर्ण स्कैन | केवल अन्वेषण |
|
||||
|
||||
**मुख्य परिणाम**: 15 गैर-तुच्छ पैटर्नों में से 7 परिपूर्ण क्लस्टरिंग उपसर्ग हिट हैं। शेष 8 एकल-विभाजन रीड हैं जिनमें इन-पार्टिशन फ़िल्टरिंग होती है। प्रत्येक क्वेरी जिसमें कम से कम एक ज्ञात तत्व होता है, वह एक विभाजन कुंजी को हिट करती है।
|
||||
|
||||
पैटर्न 16 (?, ?, ?, ?) व्यवहार में नहीं होता है क्योंकि संग्रह हमेशा निर्दिष्ट होता है, जिससे यह पैटर्न 12 में कम हो जाता है।
|
||||
|
||||
### सामान्य क्वेरी उदाहरण
|
||||
|
||||
**किसी इकाई के बारे में सब कुछ:**
|
||||
|
||||
```sql
|
||||
SELECT * FROM quads_by_entity
|
||||
WHERE collection = 'tenant1' AND entity = 'https://example.org/Alice';
|
||||
```
|
||||
|
||||
**किसी इकाई के लिए सभी बाहरी संबंध:**
|
||||
|
||||
```sql
|
||||
SELECT * FROM quads_by_entity
|
||||
WHERE collection = 'tenant1' AND entity = 'https://example.org/Alice'
|
||||
AND role = 'S';
|
||||
```
|
||||
|
||||
**किसी इकाई के लिए विशिष्ट विधेय:**
|
||||
|
||||
```sql
|
||||
SELECT * FROM quads_by_entity
|
||||
WHERE collection = 'tenant1' AND entity = 'https://example.org/Alice'
|
||||
AND role = 'S' AND p = 'https://example.org/knows';
|
||||
```
|
||||
|
||||
**किसी इकाई के लिए लेबल (विशिष्ट भाषा):**
|
||||
|
||||
```sql
|
||||
SELECT * FROM quads_by_entity
|
||||
WHERE collection = 'tenant1' AND entity = 'https://example.org/Alice'
|
||||
AND role = 'S' AND p = 'http://www.w3.org/2000/01/rdf-schema#label'
|
||||
AND otype = 'L';
|
||||
```
|
||||
|
||||
फिर, यदि आवश्यक हो, तो `lang = 'en'` एप्लिकेशन-साइड पर फ़िल्टर करें।
|
||||
|
||||
**केवल URI-मान वाले संबंध (इकाई-से-इकाई लिंक):**
|
||||
|
||||
```sql
|
||||
SELECT * FROM quads_by_entity
|
||||
WHERE collection = 'tenant1' AND entity = 'https://example.org/Alice'
|
||||
AND role = 'S' AND p = 'https://example.org/knows' AND otype = 'U';
|
||||
```
|
||||
|
||||
**रिवर्स लुकअप - यह इकाई किससे जुड़ी है:**
|
||||
|
||||
```sql
|
||||
SELECT * FROM quads_by_entity
|
||||
WHERE collection = 'tenant1' AND entity = 'https://example.org/Bob'
|
||||
AND role = 'O';
|
||||
```
|
||||
|
||||
## लेबल रिज़ॉल्यूशन और कैश वार्मिंग
|
||||
|
||||
एंटिटी-सेंट्रिक मॉडल के सबसे महत्वपूर्ण लाभों में से एक यह है कि **लेबल रिज़ॉल्यूशन एक मुफ्त साइड इफ़ेक्ट बन जाता है।**
|
||||
|
||||
पारंपरिक मल्टी-टेबल मॉडल में, लेबल प्राप्त करने के लिए अलग-अलग राउंड-ट्रिप क्वेरी की आवश्यकता होती है: ट्रिपल प्राप्त करें, परिणामों में एंटिटी यूआरआई की पहचान करें, फिर प्रत्येक के लिए `rdfs:label` प्राप्त करें। यह N+1 पैटर्न महंगा है।
|
||||
|
||||
एंटिटी-सेंट्रिक मॉडल में, किसी एंटिटी को क्वेरी करने पर, यह उसके सभी क्वाड लौटाता है - जिसमें उसके लेबल, प्रकार और अन्य गुण शामिल हैं। जब एप्लिकेशन क्वेरी परिणामों को कैश करता है, तो लेबल किसी भी चीज़ के लिए अनुरोध करने से पहले ही प्री-वार्म हो जाते हैं।
|
||||
|
||||
दो उपयोग परिदृश्य इस बात की पुष्टि करते हैं कि यह व्यवहार में अच्छी तरह से काम करता है:
|
||||
|
||||
**मानव-सामना करने वाली क्वेरी:** स्वाभाविक रूप से छोटे परिणाम सेट, लेबल आवश्यक। एंटिटी रीड कैश को प्री-वार्म करते हैं।
|
||||
**एआई/बल्क क्वेरी:** बड़े परिणाम सेट जिनमें सख्त सीमाएं होती हैं। लेबल या तो अनावश्यक होते हैं या केवल उन एंटिटीज के एक क्यूरेटेड सबसेट के लिए आवश्यक होते हैं जो पहले से ही कैश में हैं।
|
||||
|
||||
30,000 एंटिटीज जैसे विशाल परिणाम सेट के लिए लेबल को हल करने की सैद्धांतिक चिंता को इस व्यावहारिक अवलोकन द्वारा कम किया जाता है कि कोई भी मानव या एआई उपभोक्ता उन सभी लेबलों को उपयोगी रूप से संसाधित नहीं करता है। एप्लिकेशन-स्तरीय क्वेरी सीमाएं यह सुनिश्चित करती हैं कि कैश दबाव प्रबंधनीय रहे।
|
||||
|
||||
## वाइड पार्टिशन्स और रीफिकेशन
|
||||
|
||||
रीफिकेशन (आरडीएफ-स्टार शैली के स्टेटमेंट स्टेटमेंट के बारे में) हब एंटिटीज बनाते हैं - उदाहरण के लिए, एक स्रोत दस्तावेज़ जो निकाले गए हजारों तथ्यों का समर्थन करता है। इससे वाइड पार्टिशन्स बन सकते हैं।
|
||||
|
||||
कम करने वाले कारक:
|
||||
|
||||
**एप्लिकेशन-स्तरीय क्वेरी सीमाएं:** सभी GraphRAG और मानव-सामना करने वाली क्वेरी सख्त सीमाओं को लागू करती हैं, इसलिए हॉट रीड पाथ पर वाइड पार्टिशन्स को कभी भी पूरी तरह से स्कैन नहीं किया जाता है।
|
||||
**कैसेंड्रा आंशिक रीड को कुशलता से संभालता है:** एक क्लस्टरिंग कॉलम स्कैन जिसमें शुरुआती स्टॉप हो, वह बड़े पार्टिशन्स पर भी तेज़ होता है।
|
||||
**कलेक्शन डिलीशन** (केवल वह ऑपरेशन जो पूरे पार्टिशन्स को पार कर सकता है) एक स्वीकृत पृष्ठभूमि प्रक्रिया है।
|
||||
|
||||
## कलेक्शन डिलीशन
|
||||
|
||||
एपीआई कॉल द्वारा ट्रिगर किया गया, पृष्ठभूमि में चलता है (अंततः सुसंगत)।
|
||||
|
||||
1. लक्ष्य कलेक्शन के लिए `quads_by_collection` पढ़ें ताकि सभी क्वाड प्राप्त हो सकें।
|
||||
2. क्वाड से अद्वितीय एंटिटीज निकालें (s, p, o, d मान)।
|
||||
3. प्रत्येक अद्वितीय एंटिटी के लिए, `quads_by_entity` से पार्टीशन को हटाएं।
|
||||
4. `quads_by_collection` से पंक्तियों को हटाएं।
|
||||
|
||||
`quads_by_collection` टेबल वह इंडेक्स प्रदान करता है जिसकी आवश्यकता सभी एंटिटी पार्टिशन्स को खोजने के लिए होती है बिना पूरे टेबल स्कैन के। पार्टीशन-स्तरीय डिलीट कुशल हैं क्योंकि `(collection, entity)` पार्टीशन कुंजी है।
|
||||
|
||||
## मल्टी-टेबल मॉडल से माइग्रेशन पाथ
|
||||
|
||||
एंटिटी-सेंट्रिक मॉडल मौजूदा मल्टी-टेबल मॉडल के साथ माइग्रेशन के दौरान सह-अस्तित्व में रह सकता है:
|
||||
|
||||
1. मौजूदा टेबल के साथ `quads_by_entity` और `quads_by_collection` टेबल तैनात करें।
|
||||
2. नए और पुराने दोनों टेबल में नए क्वाड को डुअल-राइट करें।
|
||||
3. मौजूदा डेटा को नए टेबल में बैकफिल करें।
|
||||
4. एक क्वेरी पैटर्न को एक बार में माइग्रेट करें।
|
||||
5. सभी रीड माइग्रेट होने के बाद पुराने टेबल को डीकमीशन करें।
|
||||
|
||||
## सारांश
|
||||
|
||||
| पहलू | पारंपरिक (6-टेबल) | एंटिटी-सेंट्रिक (2-टेबल) |
|
||||
|---|---|---|
|
||||
| टेबल | 7+ | 2 |
|
||||
| क्वाड प्रति राइट | 6+ | 5 (4 डेटा + 1 मैनिफेस्ट) |
|
||||
| लेबल रिज़ॉल्यूशन | अलग राउंड ट्रिप | कैश वार्मिंग के माध्यम से मुफ्त |
|
||||
| क्वेरी पैटर्न | 6 टेबल में 16 | 1 टेबल में 16 |
|
||||
| स्कीमा जटिलता | उच्च | कम |
|
||||
| परिचालन ओवरहेड | ट्यून/मरम्मत के लिए 6 टेबल | 1 डेटा टेबल |
|
||||
| रीफिकेशन सपोर्ट | अतिरिक्त जटिलता | प्राकृतिक फिट |
|
||||
| ऑब्जेक्ट टाइप फ़िल्टरिंग | उपलब्ध नहीं | देशी (otype क्लस्टरिंग के माध्यम से) |
|
||||
228
docs/tech-specs/hi/explainability-cli.hi.md
Normal file
228
docs/tech-specs/hi/explainability-cli.hi.md
Normal file
|
|
@ -0,0 +1,228 @@
|
|||
---
|
||||
layout: default
|
||||
title: "व्याख्यात्मकता CLI तकनीकी विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# व्याख्यात्मकता CLI तकनीकी विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
## स्थिति
|
||||
|
||||
मसौदा
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह विनिर्देश ट्रस्टग्राफ में व्याख्यात्मकता डेटा को डिबग और एक्सप्लोर करने के लिए CLI टूल का वर्णन करता है। ये उपकरण उपयोगकर्ताओं को यह ट्रैक करने में सक्षम बनाते हैं कि उत्तर कैसे प्राप्त किए गए और किनारा से वापस स्रोत दस्तावेजों तक उत्पत्ति श्रृंखला को डिबग किया गया।
|
||||
|
||||
तीन CLI उपकरण:
|
||||
|
||||
1. **`tg-show-document-hierarchy`** - दस्तावेज़ → पृष्ठ → भाग → किनारा पदानुक्रम दिखाएं
|
||||
2. **`tg-list-explain-traces`** - सभी GraphRAG सत्रों को प्रश्नों के साथ सूचीबद्ध करें
|
||||
3. **`tg-show-explain-trace`** - एक सत्र के लिए पूर्ण व्याख्यात्मकता ट्रेस दिखाएं
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
**डीबगिंग**: डेवलपर्स को दस्तावेज़ प्रसंस्करण परिणामों का निरीक्षण करने में सक्षम करें
|
||||
**लेखापरीक्षा**: किसी भी निकाले गए तथ्य को उसके स्रोत दस्तावेज़ तक ट्रैक करें
|
||||
**पारदर्शिता**: सटीक रूप से दिखाएं कि GraphRAG ने उत्तर कैसे प्राप्त किया
|
||||
**उपयोगिता**: समझदार डिफ़ॉल्ट के साथ सरल CLI इंटरफ़ेस
|
||||
|
||||
## पृष्ठभूमि
|
||||
|
||||
ट्रस्टग्राफ में दो उत्पत्ति प्रणालियाँ हैं:
|
||||
|
||||
1. **निकालने के समय की उत्पत्ति** (देखें `extraction-time-provenance.md`): दस्तावेज़ → पृष्ठ → भाग → किनारा संबंधों को इनपुट के दौरान रिकॉर्ड करता है। `urn:graph:source` नामक ग्राफ में संग्रहीत, `prov:wasDerivedFrom` का उपयोग करके।
|
||||
|
||||
2. **क्वेरी-टाइम व्याख्यात्मकता** (देखें `query-time-explainability.md`): GraphRAG प्रश्नों के दौरान प्रश्न → अन्वेषण → फोकस → संश्लेषण श्रृंखला को रिकॉर्ड करता है। `urn:graph:retrieval` नामक ग्राफ में संग्रहीत।
|
||||
|
||||
वर्तमान सीमाएँ:
|
||||
प्रसंस्करण के बाद दस्तावेज़ पदानुक्रम को देखने का कोई आसान तरीका नहीं है
|
||||
व्याख्यात्मकता डेटा देखने के लिए ट्रिपल को मैन्युअल रूप से क्वेरी करना होगा
|
||||
GraphRAG सत्र का कोई समेकित दृश्य नहीं है
|
||||
|
||||
## तकनीकी डिज़ाइन
|
||||
|
||||
### टूल 1: tg-show-document-hierarchy
|
||||
|
||||
**उद्देश्य**: एक दस्तावेज़ आईडी को देखते हुए, सभी व्युत्पन्न संस्थाओं को पार करें और प्रदर्शित करें।
|
||||
|
||||
**उपयोग**:
|
||||
```bash
|
||||
tg-show-document-hierarchy "urn:trustgraph:doc:abc123"
|
||||
tg-show-document-hierarchy --show-content --max-content 500 "urn:trustgraph:doc:abc123"
|
||||
```
|
||||
|
||||
**तर्क**:
|
||||
| तर्क | विवरण |
|
||||
|-----|-------------|
|
||||
| `document_id` | दस्तावेज़ यूआरआई (स्थानिक) |
|
||||
| `-u/--api-url` | गेटवे यूआरएल (डिफ़ॉल्ट: `$TRUSTGRAPH_URL`) |
|
||||
| `-t/--token` | ऑथ टोकन (डिफ़ॉल्ट: `$TRUSTGRAPH_TOKEN`) |
|
||||
| `-U/--user` | उपयोगकर्ता आईडी (डिफ़ॉल्ट: `trustgraph`) |
|
||||
| `-C/--collection` | संग्रह (डिफ़ॉल्ट: `default`) |
|
||||
| `--show-content` | ब्लॉब/दस्तावेज़ सामग्री शामिल करें |
|
||||
| `--max-content` | प्रति ब्लॉब अधिकतम अक्षर (डिफ़ॉल्ट: 200) |
|
||||
| `--format` | आउटपुट: `tree` (डिफ़ॉल्ट), `json` |
|
||||
|
||||
**कार्यान्वयन**:
|
||||
1. ट्रिपल क्वेरी करें: `?child prov:wasDerivedFrom <document_id>` in `urn:graph:source`
|
||||
2. प्रत्येक परिणाम के बच्चों को पुनरावर्ती रूप से क्वेरी करें
|
||||
3. ट्री संरचना बनाएं: दस्तावेज़ → पृष्ठ → भाग
|
||||
4. यदि `--show-content`, तो लाइब्रेरियन एपीआई से सामग्री प्राप्त करें
|
||||
5. इंडेंटेड ट्री या JSON के रूप में प्रदर्शित करें
|
||||
|
||||
**आउटपुट उदाहरण**:
|
||||
```
|
||||
Document: urn:trustgraph:doc:abc123
|
||||
Title: "Sample PDF"
|
||||
Type: application/pdf
|
||||
|
||||
└── Page 1: urn:trustgraph:doc:abc123/p1
|
||||
├── Chunk 0: urn:trustgraph:doc:abc123/p1/c0
|
||||
│ Content: "The quick brown fox..." [truncated]
|
||||
└── Chunk 1: urn:trustgraph:doc:abc123/p1/c1
|
||||
Content: "Machine learning is..." [truncated]
|
||||
```
|
||||
|
||||
### टूल 2: tg-list-explain-traces
|
||||
|
||||
**उद्देश्य**: एक संग्रह में सभी ग्राफ़आरएजी सत्रों (प्रश्नों) को सूचीबद्ध करना।
|
||||
|
||||
**उपयोग**:
|
||||
```bash
|
||||
tg-list-explain-traces
|
||||
tg-list-explain-traces --limit 20 --format json
|
||||
```
|
||||
|
||||
**तर्क:**
|
||||
| तर्क | विवरण |
|
||||
|-----|-------------|
|
||||
| `-u/--api-url` | गेटवे यूआरएल |
|
||||
| `-t/--token` | प्रमाणीकरण टोकन |
|
||||
| `-U/--user` | उपयोगकर्ता आईडी |
|
||||
| `-C/--collection` | संग्रह |
|
||||
| `--limit` | अधिकतम परिणाम (डिफ़ॉल्ट: 50) |
|
||||
| `--format` | आउटपुट: `table` (डिफ़ॉल्ट), `json` |
|
||||
|
||||
**कार्यान्वयन:**
|
||||
1. क्वेरी: `?session tg:query ?text` को `urn:graph:retrieval` में |
|
||||
2. क्वेरी टाइमस्टैम्प: `?session prov:startedAtTime ?time` |
|
||||
3. तालिका के रूप में प्रदर्शित करें |
|
||||
|
||||
**आउटपुट उदाहरण:**
|
||||
```
|
||||
Session ID | Question | Time
|
||||
----------------------------------------------|--------------------------------|---------------------
|
||||
urn:trustgraph:question:abc123 | What was the War on Terror? | 2024-01-15 10:30:00
|
||||
urn:trustgraph:question:def456 | Who founded OpenAI? | 2024-01-15 09:15:00
|
||||
```
|
||||
|
||||
### टूल 3: tg-show-explain-trace
|
||||
|
||||
**उद्देश्य**: ग्राफ़आरएजी सत्र के लिए पूर्ण व्याख्या श्रृंखला प्रदर्शित करें।
|
||||
|
||||
**उपयोग**:
|
||||
```bash
|
||||
tg-show-explain-trace "urn:trustgraph:question:abc123"
|
||||
tg-show-explain-trace --max-answer 1000 --show-provenance "urn:trustgraph:question:abc123"
|
||||
```
|
||||
|
||||
**तर्क:**
|
||||
| तर्क | विवरण |
|
||||
|-----|-------------|
|
||||
| `question_id` | प्रश्न URI (स्थानिक) |
|
||||
| `-u/--api-url` | गेटवे URL |
|
||||
| `-t/--token` | प्रमाणीकरण टोकन |
|
||||
| `-U/--user` | उपयोगकर्ता ID |
|
||||
| `-C/--collection` | संग्रह |
|
||||
| `--max-answer` | उत्तर के लिए अधिकतम अक्षर (डिफ़ॉल्ट: 500) |
|
||||
| `--show-provenance` | स्रोत दस्तावेजों तक किनारों को ट्रेस करें |
|
||||
| `--format` | आउटपुट: `text` (डिफ़ॉल्ट), `json` |
|
||||
|
||||
**कार्यान्वयन:**
|
||||
1. `tg:query` विधेय से प्रश्न पाठ प्राप्त करें।
|
||||
2. अन्वेषण खोजें: `?exp prov:wasGeneratedBy <question_id>`
|
||||
3. फोकस खोजें: `?focus prov:wasDerivedFrom <exploration_id>`
|
||||
4. चयनित किनारों को प्राप्त करें: `<focus_id> tg:selectedEdge ?edge`
|
||||
5. प्रत्येक किनारे के लिए, `tg:edge` (उद्धृत ट्रिपल) और `tg:reasoning` प्राप्त करें।
|
||||
6. संश्लेषण खोजें: `?synth prov:wasDerivedFrom <focus_id>`
|
||||
7. लाइब्रेरियन के माध्यम से `tg:document` से उत्तर प्राप्त करें।
|
||||
8. यदि `--show-provenance`, तो स्रोत दस्तावेजों तक किनारों को ट्रेस करें।
|
||||
|
||||
**आउटपुट उदाहरण:**
|
||||
```
|
||||
=== GraphRAG Session: urn:trustgraph:question:abc123 ===
|
||||
|
||||
Question: What was the War on Terror?
|
||||
Time: 2024-01-15 10:30:00
|
||||
|
||||
--- Exploration ---
|
||||
Retrieved 50 edges from knowledge graph
|
||||
|
||||
--- Focus (Edge Selection) ---
|
||||
Selected 12 edges:
|
||||
|
||||
1. (War on Terror, definition, "A military campaign...")
|
||||
Reasoning: Directly defines the subject of the query
|
||||
Source: chunk → page 2 → "Beyond the Vigilant State"
|
||||
|
||||
2. (Guantanamo Bay, part_of, War on Terror)
|
||||
Reasoning: Shows key component of the campaign
|
||||
|
||||
--- Synthesis ---
|
||||
Answer:
|
||||
The War on Terror was a military campaign initiated...
|
||||
[truncated at 500 chars]
|
||||
```
|
||||
|
||||
## बनाने के लिए फ़ाइलें
|
||||
|
||||
| फ़ाइल | उद्देश्य |
|
||||
|------|---------|
|
||||
| `trustgraph-cli/trustgraph/cli/show_document_hierarchy.py` | टूल 1 |
|
||||
| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | टूल 2 |
|
||||
| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | टूल 3 |
|
||||
|
||||
## बदलने के लिए फ़ाइलें
|
||||
|
||||
| फ़ाइल | परिवर्तन |
|
||||
|------|--------|
|
||||
| `trustgraph-cli/setup.py` | console_scripts प्रविष्टियाँ जोड़ें |
|
||||
|
||||
## कार्यान्वयन नोट्स
|
||||
|
||||
1. **बाइनरी सामग्री सुरक्षा**: UTF-8 डिकोड करने का प्रयास करें; यदि विफल रहता है, तो `[Binary: {size} bytes]` प्रदर्शित करें।
|
||||
2. **छंटनी**: `--max-content`/`--max-answer` का सम्मान करें जिसमें `[truncated]` संकेतक हो।
|
||||
3. **उद्धृत तिगुट**: `tg:edge` विधेय से RDF-स्टार प्रारूप को पार्स करें।
|
||||
4. **पैटर्न**: `query_graph.py` से मौजूदा CLI पैटर्न का पालन करें।
|
||||
|
||||
## सुरक्षा विचार
|
||||
|
||||
सभी क्वेरी उपयोगकर्ता/संग्रह सीमाओं का सम्मान करती हैं।
|
||||
`--token` या `$TRUSTGRAPH_TOKEN` के माध्यम से टोकन प्रमाणीकरण समर्थित है।
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
नमूना डेटा के साथ मैन्युअल सत्यापन:
|
||||
```bash
|
||||
# Load a test document
|
||||
tg-load-pdf -f test.pdf -c test-collection
|
||||
|
||||
# Verify hierarchy
|
||||
tg-show-document-hierarchy "urn:trustgraph:doc:test"
|
||||
|
||||
# Run a GraphRAG query with explainability
|
||||
tg-invoke-graph-rag --explainable -q "Test question"
|
||||
|
||||
# List and inspect traces
|
||||
tg-list-explain-traces
|
||||
tg-show-explain-trace "urn:trustgraph:question:xxx"
|
||||
```
|
||||
|
||||
## संदर्भ
|
||||
|
||||
क्वेरी-टाइम व्याख्यात्मकता: `docs/tech-specs/query-time-explainability.md`
|
||||
निष्कर्षण-टाइम उत्पत्ति: `docs/tech-specs/extraction-time-provenance.md`
|
||||
मौजूदा CLI उदाहरण: `trustgraph-cli/trustgraph/cli/invoke_graph_rag.py`
|
||||
355
docs/tech-specs/hi/extraction-flows.hi.md
Normal file
355
docs/tech-specs/hi/extraction-flows.hi.md
Normal file
|
|
@ -0,0 +1,355 @@
|
|||
---
|
||||
layout: default
|
||||
title: "निष्कर्षण प्रवाह (निकालने की प्रक्रियाएं)"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# निष्कर्षण प्रवाह (निकालने की प्रक्रियाएं)
|
||||
|
||||
> **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.
|
||||
|
||||
यह दस्तावेज़ बताता है कि डेटा ट्रस्टग्राफ निष्कर्षण पाइपलाइन के माध्यम से कैसे प्रवाहित होता है, दस्तावेज़ जमा करने से लेकर ज्ञान भंडारों में भंडारण तक।
|
||||
|
||||
## अवलोकन
|
||||
|
||||
```
|
||||
┌──────────┐ ┌─────────────┐ ┌─────────┐ ┌────────────────────┐
|
||||
│ Librarian│────▶│ PDF Decoder │────▶│ Chunker │────▶│ Knowledge │
|
||||
│ │ │ (PDF only) │ │ │ │ Extraction │
|
||||
│ │────────────────────────▶│ │ │ │
|
||||
└──────────┘ └─────────────┘ └─────────┘ └────────────────────┘
|
||||
│ │
|
||||
│ ├──▶ Triples
|
||||
│ ├──▶ Entity Contexts
|
||||
│ └──▶ Rows
|
||||
│
|
||||
└──▶ Document Embeddings
|
||||
```
|
||||
|
||||
## सामग्री भंडारण
|
||||
|
||||
### ब्लॉब भंडारण (S3/Minio)
|
||||
|
||||
दस्तावेज़ सामग्री S3-संगत ब्लॉब भंडारण में संग्रहीत की जाती है:
|
||||
पथ प्रारूप: `doc/{object_id}` जहाँ object_id एक UUID है
|
||||
सभी दस्तावेज़ प्रकार यहां संग्रहीत किए जाते हैं: स्रोत दस्तावेज़, पृष्ठ, खंड
|
||||
|
||||
### मेटाडेटा भंडारण (कैसेंड्रा)
|
||||
|
||||
कैसेंड्रा में संग्रहीत दस्तावेज़ मेटाडेटा में शामिल हैं:
|
||||
दस्तावेज़ आईडी, शीर्षक, प्रकार (MIME प्रकार)
|
||||
ब्लॉब भंडारण के लिए `object_id` संदर्भ
|
||||
चाइल्ड दस्तावेज़ों (पृष्ठों, खंडों) के लिए `parent_id`
|
||||
`document_type`: "स्रोत", "पृष्ठ", "खंड", "उत्तर"
|
||||
|
||||
### इनलाइन बनाम स्ट्रीमिंग थ्रेशोल्ड
|
||||
|
||||
सामग्री प्रेषण एक आकार-आधारित रणनीति का उपयोग करता है:
|
||||
**< 2MB**: सामग्री संदेश में इनलाइन शामिल है (base64-एन्कोडेड)
|
||||
**≥ 2MB**: केवल `document_id` भेजा जाता है; प्रोसेसर लाइब्रेरियन API के माध्यम से प्राप्त करता है
|
||||
|
||||
## चरण 1: दस्तावेज़ सबमिशन (लाइब्रेरियन)
|
||||
|
||||
### प्रवेश बिंदु
|
||||
|
||||
दस्तावेज़ लाइब्रेरियन के `add-document` ऑपरेशन के माध्यम से सिस्टम में प्रवेश करते हैं:
|
||||
1. सामग्री को ब्लॉब भंडारण में अपलोड किया जाता है
|
||||
2. कैसेंड्रा में मेटाडेटा रिकॉर्ड बनाया जाता है
|
||||
3. दस्तावेज़ आईडी वापस करता है
|
||||
|
||||
### निष्कर्षण को ट्रिगर करना
|
||||
|
||||
`add-processing` ऑपरेशन निष्कर्षण को ट्रिगर करता है:
|
||||
`document_id`, `flow` (पाइपलाइन आईडी), `collection` (लक्ष्य स्टोर) निर्दिष्ट करता है
|
||||
लाइब्रेरियन का `load_document()` सामग्री प्राप्त करता है और फ्लो इनपुट कतार पर प्रकाशित करता है
|
||||
|
||||
### स्कीमा: दस्तावेज़
|
||||
|
||||
```
|
||||
Document
|
||||
├── metadata: Metadata
|
||||
│ ├── id: str # Document identifier
|
||||
│ ├── user: str # Tenant/user ID
|
||||
│ ├── collection: str # Target collection
|
||||
│ └── metadata: list[Triple] # (largely unused, historical)
|
||||
├── data: bytes # PDF content (base64, if inline)
|
||||
└── document_id: str # Librarian reference (if streaming)
|
||||
```
|
||||
|
||||
**राउटिंग (Routing)**: `kind` फ़ील्ड के आधार पर:
|
||||
`application/pdf` → `document-load` क्यू → पीडीएफ डिकोडर
|
||||
`text/plain` → `text-load` क्यू → चंकर
|
||||
|
||||
## चरण 2: पीडीएफ डिकोडर
|
||||
|
||||
पीडीएफ दस्तावेजों को टेक्स्ट पृष्ठों में परिवर्तित करता है।
|
||||
|
||||
### प्रक्रिया
|
||||
|
||||
1. सामग्री प्राप्त करें (इनलाइन `data` या लाइब्रेरियन से `document_id` के माध्यम से)
|
||||
2. PyPDF का उपयोग करके पृष्ठों को निकालें
|
||||
3. प्रत्येक पृष्ठ के लिए:
|
||||
लाइब्रेरियन में चाइल्ड दस्तावेज़ के रूप में सहेजें (`{doc_id}/p{page_num}`)
|
||||
प्रामाणिकता ट्रिपल उत्सर्जित करें (पृष्ठ दस्तावेज़ से प्राप्त है)
|
||||
चंकर को अग्रेषित करें
|
||||
|
||||
### स्कीमा: TextDocument
|
||||
|
||||
```
|
||||
TextDocument
|
||||
├── metadata: Metadata
|
||||
│ ├── id: str # Page URI (e.g., https://trustgraph.ai/doc/xxx/p1)
|
||||
│ ├── user: str
|
||||
│ ├── collection: str
|
||||
│ └── metadata: list[Triple]
|
||||
├── text: bytes # Page text content (if inline)
|
||||
└── document_id: str # Librarian reference (e.g., "doc123/p1")
|
||||
```
|
||||
|
||||
## चरण 3: चंकर (Chunker)
|
||||
|
||||
यह टेक्स्ट को कॉन्फ़िगर किए गए आकार में टुकड़ों में विभाजित करता है।
|
||||
|
||||
### पैरामीटर (फ्लो-कॉन्फ़िगर करने योग्य)
|
||||
|
||||
`chunk_size`: अक्षरों में लक्षित टुकड़ा आकार (डिफ़ॉल्ट: 2000)
|
||||
`chunk_overlap`: टुकड़ों के बीच ओवरलैप (डिफ़ॉल्ट: 100)
|
||||
|
||||
### प्रक्रिया
|
||||
|
||||
1. टेक्स्ट सामग्री प्राप्त करें (इनलाइन या लाइब्रेरियन के माध्यम से)
|
||||
2. रिकर्सिव कैरेक्टर स्प्लिटर का उपयोग करके विभाजित करें
|
||||
3. प्रत्येक टुकड़े के लिए:
|
||||
लाइब्रेरियन में चाइल्ड दस्तावेज़ के रूप में सहेजें (`{parent_id}/c{index}`)
|
||||
प्रामाणिकता ट्रिपल उत्सर्जित करें (टुकड़ा पृष्ठ/दस्तावेज़ से प्राप्त हुआ है)
|
||||
निष्कर्षण प्रोसेसर को अग्रेषित करें
|
||||
|
||||
### स्कीमा: टुकड़ा (Chunk)
|
||||
|
||||
```
|
||||
Chunk
|
||||
├── metadata: Metadata
|
||||
│ ├── id: str # Chunk URI
|
||||
│ ├── user: str
|
||||
│ ├── collection: str
|
||||
│ └── metadata: list[Triple]
|
||||
├── chunk: bytes # Chunk text content
|
||||
└── document_id: str # Librarian chunk ID (e.g., "doc123/p1/c3")
|
||||
```
|
||||
|
||||
### दस्तावेज़ आईडी पदानुक्रम
|
||||
|
||||
चाइल्ड दस्तावेज़ अपनी उत्पत्ति को आईडी में एन्कोड करते हैं:
|
||||
स्रोत: `doc123`
|
||||
पृष्ठ: `doc123/p5`
|
||||
पृष्ठ से अंश: `doc123/p5/c2`
|
||||
पाठ से अंश: `doc123/c2`
|
||||
|
||||
## चरण 4: ज्ञान निष्कर्षण
|
||||
|
||||
कई निष्कर्षण पैटर्न उपलब्ध हैं, जिन्हें प्रवाह कॉन्फ़िगरेशन द्वारा चुना जाता है।
|
||||
|
||||
### पैटर्न ए: बेसिक ग्राफआरएजी
|
||||
|
||||
दो समानांतर प्रोसेसर:
|
||||
|
||||
**kg-extract-definitions**
|
||||
इनपुट: अंश
|
||||
आउटपुट: ट्रिपल (इकाई परिभाषाएँ), एंटिटीकॉन्टेक्स्ट
|
||||
निष्कर्षण: इकाई लेबल, परिभाषाएँ
|
||||
|
||||
**kg-extract-relationships**
|
||||
इनपुट: अंश
|
||||
आउटपुट: ट्रिपल (संबंध), एंटिटीकॉन्टेक्स्ट
|
||||
निष्कर्षण: विषय-क्रिया-वस्तु संबंध
|
||||
|
||||
### पैटर्न बी: ऑन्टोलॉजी-संचालित (kg-extract-ontology)
|
||||
|
||||
इनपुट: अंश
|
||||
आउटपुट: ट्रिपल, एंटिटीकॉन्टेक्स्ट
|
||||
निष्कर्षण को निर्देशित करने के लिए कॉन्फ़िगर की गई ऑन्टोलॉजी का उपयोग करता है
|
||||
|
||||
### पैटर्न सी: एजेंट-आधारित (kg-extract-agent)
|
||||
|
||||
इनपुट: अंश
|
||||
आउटपुट: ट्रिपल, एंटिटीकॉन्टेक्स्ट
|
||||
निष्कर्षण के लिए एजेंट फ्रेमवर्क का उपयोग करता है
|
||||
|
||||
### पैटर्न डी: पंक्ति निष्कर्षण (kg-extract-rows)
|
||||
|
||||
इनपुट: अंश
|
||||
आउटपुट: पंक्तियाँ (संरचित डेटा, ट्रिपल नहीं)
|
||||
संरचित रिकॉर्ड निकालने के लिए स्कीमा परिभाषा का उपयोग करता है
|
||||
|
||||
### स्कीमा: ट्रिपल
|
||||
|
||||
```
|
||||
Triples
|
||||
├── metadata: Metadata
|
||||
│ ├── id: str
|
||||
│ ├── user: str
|
||||
│ ├── collection: str
|
||||
│ └── metadata: list[Triple] # (set to [] by extractors)
|
||||
└── triples: list[Triple]
|
||||
└── Triple
|
||||
├── s: Term # Subject
|
||||
├── p: Term # Predicate
|
||||
├── o: Term # Object
|
||||
└── g: str | None # Named graph
|
||||
```
|
||||
|
||||
### स्कीमा: एंटिटीकॉन्टेक्स्ट्स
|
||||
|
||||
```
|
||||
EntityContexts
|
||||
├── metadata: Metadata
|
||||
└── entities: list[EntityContext]
|
||||
└── EntityContext
|
||||
├── entity: Term # Entity identifier (IRI)
|
||||
├── context: str # Textual description for embedding
|
||||
└── chunk_id: str # Source chunk ID (provenance)
|
||||
```
|
||||
|
||||
### स्कीमा: पंक्तियाँ
|
||||
|
||||
```
|
||||
Rows
|
||||
├── metadata: Metadata
|
||||
├── row_schema: RowSchema
|
||||
│ ├── name: str
|
||||
│ ├── description: str
|
||||
│ └── fields: list[Field]
|
||||
└── rows: list[dict[str, str]] # Extracted records
|
||||
```
|
||||
|
||||
## चरण 5: एम्बेडिंग पीढ़ी
|
||||
|
||||
### ग्राफ एम्बेडिंग
|
||||
|
||||
इकाई संदर्भों को वेक्टर एम्बेडिंग में परिवर्तित करता है।
|
||||
|
||||
**प्रक्रिया:**
|
||||
1. इकाई संदर्भ प्राप्त करें
|
||||
2. संदर्भ पाठ के साथ एम्बेडिंग सेवा को कॉल करें
|
||||
3. ग्राफ एम्बेडिंग आउटपुट करें (इकाई → वेक्टर मैपिंग)
|
||||
|
||||
**स्कीमा: ग्राफ एम्बेडिंग**
|
||||
|
||||
```
|
||||
GraphEmbeddings
|
||||
├── metadata: Metadata
|
||||
└── entities: list[EntityEmbeddings]
|
||||
└── EntityEmbeddings
|
||||
├── entity: Term # Entity identifier
|
||||
├── vector: list[float] # Embedding vector
|
||||
└── chunk_id: str # Source chunk (provenance)
|
||||
```
|
||||
|
||||
### दस्तावेज़ एम्बेडिंग
|
||||
|
||||
यह सीधे टेक्स्ट के टुकड़ों को वेक्टर एम्बेडिंग में परिवर्तित करता है।
|
||||
|
||||
**प्रक्रिया:**
|
||||
1. टेक्स्ट का टुकड़ा प्राप्त करें
|
||||
2. टेक्स्ट के टुकड़े के साथ एम्बेडिंग सेवा को कॉल करें
|
||||
3. दस्तावेज़एम्बेडिंग आउटपुट करें
|
||||
|
||||
**स्कीमा: दस्तावेज़एम्बेडिंग**
|
||||
|
||||
```
|
||||
DocumentEmbeddings
|
||||
├── metadata: Metadata
|
||||
└── chunks: list[ChunkEmbeddings]
|
||||
└── ChunkEmbeddings
|
||||
├── chunk_id: str # Chunk identifier
|
||||
└── vector: list[float] # Embedding vector
|
||||
```
|
||||
|
||||
### पंक्ति एम्बेडिंग (पंक्ति एम्बेडिंग)
|
||||
|
||||
पंक्ति अनुक्रमणिका फ़ील्ड को वेक्टर एम्बेडिंग में परिवर्तित करता है।
|
||||
|
||||
**प्रक्रिया:**
|
||||
1. पंक्तियों को प्राप्त करें
|
||||
2. कॉन्फ़िगर की गई अनुक्रमणिका फ़ील्ड को एम्बेड करें
|
||||
3. पंक्ति वेक्टर स्टोर पर आउटपुट करें
|
||||
|
||||
## चरण 6: भंडारण (चरण 6: भंडारण)
|
||||
|
||||
### ट्रिपल स्टोर (ट्रिपल स्टोर)
|
||||
|
||||
प्राप्त करता है: ट्रिपल (प्राप्त करता है: ट्रिपल)
|
||||
भंडारण: कैसेंड्रा (इकाई-केंद्रित तालिकाएँ) (भंडारण: कैसेंड्रा (इकाई-केंद्रित तालिकाएँ))
|
||||
नामित ग्राफ मूल ज्ञान को उत्पत्ति से अलग करते हैं: (नामित ग्राफ मूल ज्ञान को उत्पत्ति से अलग करते हैं:)
|
||||
`""` (डिफ़ॉल्ट): मूल ज्ञान तथ्य (डिफ़ॉल्ट: मूल ज्ञान तथ्य)
|
||||
`urn:graph:source`: निष्कर्षण उत्पत्ति (निष्कर्षण उत्पत्ति)
|
||||
`urn:graph:retrieval`: क्वेरी-टाइम व्याख्या (क्वेरी-टाइम व्याख्या)
|
||||
|
||||
### वेक्टर स्टोर (ग्राफ एम्बेडिंग) (वेक्टर स्टोर (ग्राफ एम्बेडिंग))
|
||||
|
||||
प्राप्त करता है: GraphEmbeddings (प्राप्त करता है: GraphEmbeddings)
|
||||
भंडारण: Qdrant, Milvus, या Pinecone (भंडारण: Qdrant, Milvus, या Pinecone)
|
||||
अनुक्रमित: इकाई IRI द्वारा (अनुक्रमित: इकाई IRI द्वारा)
|
||||
मेटाडेटा: उत्पत्ति के लिए chunk_id (मेटाडेटा: उत्पत्ति के लिए chunk_id)
|
||||
|
||||
### वेक्टर स्टोर (दस्तावेज़ एम्बेडिंग) (वेक्टर स्टोर (दस्तावेज़ एम्बेडिंग))
|
||||
|
||||
प्राप्त करता है: DocumentEmbeddings (प्राप्त करता है: DocumentEmbeddings)
|
||||
भंडारण: Qdrant, Milvus, या Pinecone (भंडारण: Qdrant, Milvus, या Pinecone)
|
||||
अनुक्रमित: chunk_id द्वारा (अनुक्रमित: chunk_id द्वारा)
|
||||
|
||||
### पंक्ति स्टोर (पंक्ति स्टोर)
|
||||
|
||||
प्राप्त करता है: Rows (प्राप्त करता है: Rows)
|
||||
भंडारण: कैसेंड्रा (भंडारण: कैसेंड्रा)
|
||||
स्कीमा-संचालित तालिका संरचना (स्कीमा-संचालित तालिका संरचना)
|
||||
|
||||
### पंक्ति वेक्टर स्टोर (पंक्ति वेक्टर स्टोर)
|
||||
|
||||
प्राप्त होता है: पंक्ति एम्बेडिंग (पंक्ति एम्बेडिंग)
|
||||
भंडारण: वेक्टर डेटाबेस (वेक्टर डेटाबेस)
|
||||
अनुक्रमित किया गया: पंक्ति अनुक्रमणिका फ़ील्ड द्वारा (पंक्ति अनुक्रमणिका फ़ील्ड द्वारा)
|
||||
|
||||
## मेटाडेटा फ़ील्ड विश्लेषण (मेटाडेटा फ़ील्ड विश्लेषण)
|
||||
|
||||
### सक्रिय रूप से उपयोग किए जाने वाले फ़ील्ड (सक्रिय रूप से उपयोग किए जाने वाले फ़ील्ड)
|
||||
|
||||
| फ़ील्ड | उपयोग |
|
||||
|-------|-------|
|
||||
| `metadata.id` | दस्तावेज़/चंक पहचानकर्ता, लॉगिंग, उत्पत्ति (दस्तावेज़/चंक पहचानकर्ता, लॉगिंग, उत्पत्ति)
|
||||
| `metadata.user` | मल्टी-टेनेंसी, स्टोरेज रूटिंग (मल्टी-टेनेंसी, स्टोरेज रूटिंग)
|
||||
| `metadata.collection` | लक्ष्य संग्रह चयन (लक्ष्य संग्रह चयन)
|
||||
| `document_id` | लाइब्रेरियन संदर्भ, उत्पत्ति लिंकिंग (लाइब्रेरियन संदर्भ, उत्पत्ति लिंकिंग)
|
||||
| `chunk_id` | पाइपलाइन के माध्यम से उत्पत्ति ट्रैकिंग (पाइपलाइन के माध्यम से उत्पत्ति ट्रैकिंग)
|
||||
|
||||
<<<<<<< HEAD
|
||||
### संभावित रूप से अनावश्यक फ़ील्ड (संभावित रूप से अनावश्यक फ़ील्ड)
|
||||
|
||||
| फ़ील्ड | स्थिति |
|
||||
|-------|--------|
|
||||
| `metadata.metadata` | सभी एक्सट्रैक्टरों द्वारा `[]` पर सेट; दस्तावेज़-स्तरीय मेटाडेटा अब सबमिशन के समय लाइब्रेरियन द्वारा संभाला जाता है (सभी एक्सट्रैक्टरों द्वारा `[]` पर सेट; दस्तावेज़-स्तरीय मेटाडेटा अब सबमिशन के समय लाइब्रेरियन द्वारा संभाला जाता है)
|
||||
=======
|
||||
### हटाए गए फ़ील्ड (हटाए गए फ़ील्ड)
|
||||
|
||||
| फ़ील्ड | स्थिति |
|
||||
|-------|--------|
|
||||
| `metadata.metadata` | `Metadata` वर्ग से हटा दिया गया। दस्तावेज़-स्तरीय मेटाडेटा ट्रिपल अब सीधे लाइब्रेरियन द्वारा ट्रिपल स्टोर को सबमिशन के समय भेजा जाता है, न कि निष्कर्षण पाइपलाइन के माध्यम से (`Metadata` वर्ग से हटा दिया गया। दस्तावेज़-स्तरीय मेटाडेटा ट्रिपल अब सीधे लाइब्रेरियन द्वारा ट्रिपल स्टोर को सबमिशन के समय भेजा जाता है, न कि निष्कर्षण पाइपलाइन के माध्यम से)
|
||||
>>>>>>> e3bcbf73 (The metadata field (list of triples) in the pipeline Metadata class)
|
||||
|
||||
### बाइट्स फ़ील्ड पैटर्न (बाइट्स फ़ील्ड पैटर्न)
|
||||
|
||||
सभी सामग्री फ़ील्ड (`data`, `text`, `chunk`) `bytes` हैं लेकिन सभी प्रोसेसरों द्वारा तुरंत UTF-8 स्ट्रिंग में डिकोड किए जाते हैं। कोई भी प्रोसेसर कच्चे बाइट्स का उपयोग नहीं करता है।
|
||||
|
||||
## फ्लो कॉन्फ़िगरेशन (फ्लो कॉन्फ़िगरेशन)
|
||||
|
||||
फ्लो बाहरी रूप से परिभाषित किए जाते हैं और कॉन्फ़िगरेशन सेवा के माध्यम से लाइब्रेरियन को प्रदान किए जाते हैं। प्रत्येक फ्लो में निम्नलिखित निर्दिष्ट होता है:
|
||||
|
||||
इनपुट क्यू (इनपुट क्यू) (`text-load`, `document-load`)
|
||||
प्रोसेसर श्रृंखला (प्रोसेसर श्रृंखला)
|
||||
पैरामीटर (चंक आकार, निष्कर्षण विधि, आदि) (पैरामीटर (चंक आकार, निष्कर्षण विधि, आदि))
|
||||
|
||||
फ्लो पैटर्न के उदाहरण: (फ्लो पैटर्न के उदाहरण:)
|
||||
`pdf-graphrag`: PDF → Decoder → Chunker → Definitions + Relationships → Embeddings
|
||||
`text-graphrag`: Text → Chunker → Definitions + Relationships → Embeddings
|
||||
`pdf-ontology`: PDF → Decoder → Chunker → Ontology Extraction → Embeddings
|
||||
`text-rows`: Text → Chunker → Row Extraction → Row Store
|
||||
260
docs/tech-specs/hi/extraction-provenance-subgraph.hi.md
Normal file
260
docs/tech-specs/hi/extraction-provenance-subgraph.hi.md
Normal file
|
|
@ -0,0 +1,260 @@
|
|||
---
|
||||
layout: default
|
||||
title: "निष्कर्षण का स्रोत: सबग्राफ मॉडल"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# निष्कर्षण का स्रोत: सबग्राफ मॉडल
|
||||
|
||||
> **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.
|
||||
|
||||
## समस्या
|
||||
|
||||
निष्कर्षण के समय का वर्तमान स्रोत जानकारी एक पूर्ण पुन: निरूपण प्रति उत्पन्न करता है
|
||||
निष्कर्षित त्रिगुट: प्रत्येक ज्ञान तथ्य के लिए एक अद्वितीय `stmt_uri`, `activity_uri`, और संबंधित
|
||||
<<<<<<< HEAD
|
||||
PROV-O मेटाडेटा। एक ऐसे खंड को संसाधित करना जो 20 संबंधों का उत्पादन करता है, उसमें लगभग 220 स्रोत जानकारी त्रिगुट होते हैं, इसके अतिरिक्त
|
||||
=======
|
||||
PROV-O मेटाडेटा। एक ऐसे खंड को संसाधित करना जो 20 संबंध उत्पन्न करता है, उसमें लगभग 220 स्रोत जानकारी त्रिगुट होते हैं, इसके अतिरिक्त
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
लगभग 20 ज्ञान त्रिगुट - लगभग 10:1 का ओवरहेड।
|
||||
|
||||
|
||||
यह महंगा है (भंडारण, अनुक्रमण, प्रसारण) और अर्थपूर्ण रूप से
|
||||
गलत है। प्रत्येक खंड को एक एकल LLM कॉल द्वारा संसाधित किया जाता है जो सभी त्रिगुटों को एक लेनदेन में उत्पन्न करता है।
|
||||
वर्तमान प्रति-त्रिगुट मॉडल 20 स्वतंत्र निष्कर्षण
|
||||
घटनाओं का भ्रम पैदा करके इसे अस्पष्ट करता है।
|
||||
|
||||
|
||||
इसके अतिरिक्त, चार निष्कर्षण प्रोसेसरों में से दो (kg-extract-ontology,
|
||||
kg-extract-agent) में कोई स्रोत जानकारी नहीं है, जिससे ऑडिट
|
||||
में अंतराल पैदा होते हैं।
|
||||
|
||||
## समाधान
|
||||
|
||||
प्रति-त्रिगुट पुन: निरूपण को एक **सबग्राफ मॉडल** से बदलें: एक स्रोत जानकारी
|
||||
रिकॉर्ड प्रति खंड निष्कर्षण, उस खंड से उत्पन्न सभी त्रिगुटों में साझा किया जाता है।
|
||||
|
||||
|
||||
### शब्दावली परिवर्तन
|
||||
|
||||
| पुराना | नया |
|
||||
|-----|-----|
|
||||
| `stmt_uri` (`https://trustgraph.ai/stmt/{uuid}`) | `subgraph_uri` (`https://trustgraph.ai/subgraph/{uuid}`) |
|
||||
| `statement_uri()` | `subgraph_uri()` |
|
||||
| `tg:reifies` (1:1, पहचान) | `tg:contains` (1:कई, समावेशन) |
|
||||
|
||||
### लक्षित संरचना
|
||||
|
||||
सभी स्रोत जानकारी त्रिगुट `urn:graph:source` नामित ग्राफ में जाते हैं।
|
||||
|
||||
```
|
||||
# Subgraph contains each extracted triple (RDF-star quoted triples)
|
||||
<subgraph> tg:contains <<s1 p1 o1>> .
|
||||
<subgraph> tg:contains <<s2 p2 o2>> .
|
||||
<subgraph> tg:contains <<s3 p3 o3>> .
|
||||
|
||||
# Derivation from source chunk
|
||||
<subgraph> prov:wasDerivedFrom <chunk_uri> .
|
||||
<subgraph> prov:wasGeneratedBy <activity> .
|
||||
|
||||
# Activity: one per chunk extraction
|
||||
<activity> rdf:type prov:Activity .
|
||||
<activity> rdfs:label "{component_name} extraction" .
|
||||
<activity> prov:used <chunk_uri> .
|
||||
<activity> prov:wasAssociatedWith <agent> .
|
||||
<activity> prov:startedAtTime "2026-03-13T10:00:00Z" .
|
||||
<activity> tg:componentVersion "0.25.0" .
|
||||
<activity> tg:llmModel "gpt-4" . # if available
|
||||
<activity> tg:ontology <ontology_uri> . # if available
|
||||
|
||||
# Agent: stable per component
|
||||
<agent> rdf:type prov:Agent .
|
||||
<agent> rdfs:label "{component_name}" .
|
||||
```
|
||||
|
||||
### मात्रा की तुलना
|
||||
|
||||
<<<<<<< HEAD
|
||||
एक ऐसे खंड के लिए जो N निकाले गए त्रिगुण उत्पन्न करता है:
|
||||
=======
|
||||
एक ऐसे खंड के लिए जो N निकाले गए त्रिगुण (ट्रिपल्स) उत्पन्न करता है:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
| | पुराना (प्रति-त्रिगुण) | नया (उप-ग्राफ) |
|
||||
|---|---|---|
|
||||
| `tg:contains` / `tg:reifies` | N | N |
|
||||
| गतिविधि त्रिगुण | ~9 x N | ~9 |
|
||||
| एजेंट त्रिगुण | 2 x N | 2 |
|
||||
| कथन/उप-ग्राफ मेटाडेटा | 2 x N | 2 |
|
||||
| **कुल प्रामाणिकता त्रिगुण** | **~13N** | **N + 13** |
|
||||
| **उदाहरण (N=20)** | **~260** | **33** |
|
||||
|
||||
## दायरा
|
||||
|
||||
### अपडेट करने के लिए प्रोसेसर (मौजूदा प्रामाणिकता, प्रति-त्रिगुण)
|
||||
|
||||
**kg-extract-definitions**
|
||||
(`trustgraph-flow/trustgraph/extract/kg/definitions/extract.py`)
|
||||
|
||||
वर्तमान में, यह `statement_uri()` + `triple_provenance_triples()` को परिभाषा के प्रत्येक लूप के अंदर कॉल करता है।
|
||||
|
||||
|
||||
परिवर्तन:
|
||||
लूप से पहले `subgraph_uri()` और `activity_uri()` का निर्माण करें।
|
||||
लूप के अंदर `tg:contains` त्रिकों को एकत्र करें।
|
||||
लूप के बाद एक बार साझा गतिविधि/एजेंट/व्युत्पत्ति ब्लॉक उत्सर्जित करें।
|
||||
|
||||
**kg-extract-relationships**
|
||||
(`trustgraph-flow/trustgraph/extract/kg/relationships/extract.py`)
|
||||
|
||||
परिभाषाओं के समान पैटर्न। समान परिवर्तन।
|
||||
|
||||
### उत्पत्ति जोड़ने के लिए प्रोसेसर (वर्तमान में गायब)
|
||||
|
||||
**kg-extract-ontology**
|
||||
(`trustgraph-flow/trustgraph/extract/kg/ontology/extract.py`)
|
||||
|
||||
<<<<<<< HEAD
|
||||
वर्तमान में, यह बिना किसी स्रोत जानकारी के त्रिक उत्पन्न करता है। उपग्राफ स्रोत जानकारी जोड़ें।
|
||||
उसी पैटर्न का उपयोग करके: प्रत्येक खंड के लिए एक उपग्राफ, प्रत्येक के लिए `tg:contains`।
|
||||
निकाले गए त्रिगुट।
|
||||
=======
|
||||
वर्तमान में, यह बिना किसी स्रोत जानकारी के त्रिक (triples) उत्पन्न करता है। उप-ग्राफ (subgraph) की स्रोत जानकारी जोड़ें।
|
||||
उसी पैटर्न का उपयोग करके: प्रत्येक खंड (chunk) के लिए एक उप-ग्राफ, प्रत्येक निकाले गए त्रिक के लिए `tg:contains`।
|
||||
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**kg-extract-agent**
|
||||
(`trustgraph-flow/trustgraph/extract/kg/agent/extract.py`)
|
||||
|
||||
<<<<<<< HEAD
|
||||
वर्तमान में, यह बिना किसी स्रोत जानकारी के त्रिक (triples) उत्पन्न करता है। समान पैटर्न का उपयोग करके सबग्राफ (subgraph) स्रोत जानकारी जोड़ें।
|
||||
|
||||
|
||||
### साझा उत्पत्ति लाइब्रेरी में परिवर्तन
|
||||
|
||||
**`trustgraph-base/trustgraph/provenance/triples.py`**
|
||||
|
||||
`triple_provenance_triples()` को `subgraph_provenance_triples()` से बदलें
|
||||
नया फ़ंक्शन एक एकल के बजाय निकाले गए त्रिपुलों की सूची को स्वीकार करता है
|
||||
प्रत्येक ट्रिपल के लिए एक `tg:contains` उत्पन्न करता है, साझा गतिविधि/एजेंट ब्लॉक
|
||||
पुराने `triple_provenance_triples()` को हटा दें
|
||||
=======
|
||||
वर्तमान में, यह बिना किसी स्रोत जानकारी के त्रिक (triples) उत्पन्न करता है। उप-ग्राफ (subgraph) की स्रोत जानकारी उसी पैटर्न का उपयोग करके जोड़ें।
|
||||
|
||||
|
||||
### साझा स्रोत पुस्तकालय (Shared Provenance Library) में परिवर्तन
|
||||
|
||||
**`trustgraph-base/trustgraph/provenance/triples.py`**
|
||||
|
||||
`triple_provenance_triples()` को `subgraph_provenance_triples()` से बदलें।
|
||||
नया फ़ंक्शन एक एकल त्रिक के बजाय निकाले गए त्रिकों की एक सूची स्वीकार करता है।
|
||||
प्रत्येक त्रिक के लिए एक `tg:contains` उत्पन्न करता है, जो साझा गतिविधि/एजेंट ब्लॉक है।
|
||||
पुराने `triple_provenance_triples()` को हटा दें।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**`trustgraph-base/trustgraph/provenance/uris.py`**
|
||||
|
||||
`statement_uri()` को `subgraph_uri()` से बदलें।
|
||||
|
||||
**`trustgraph-base/trustgraph/provenance/namespaces.py`**
|
||||
|
||||
`TG_REIFIES` को `TG_CONTAINS` से बदलें।
|
||||
|
||||
### दायरे में नहीं
|
||||
|
||||
<<<<<<< HEAD
|
||||
**kg-extract-topics**: पुराना-शैली का प्रोसेसर, वर्तमान में उपयोग में नहीं है।
|
||||
मानक प्रक्रियाओं में।
|
||||
**kg-extract-rows**: पंक्तियाँ उत्पन्न करता है, ट्रिपल नहीं, अलग उत्पत्ति मॉडल।
|
||||
मॉडल।
|
||||
**क्वेरी-टाइम प्रोवेनेंस** (`urn:graph:retrieval`): एक अलग चिंता का विषय,
|
||||
पहले से ही एक अलग पैटर्न का उपयोग करता है (प्रश्न/अन्वेषण/फोकस/संश्लेषण)।
|
||||
=======
|
||||
**kg-extract-topics**: पुराना शैली का प्रोसेसर, वर्तमान में उपयोग में नहीं है।
|
||||
मानक प्रक्रियाओं में।
|
||||
**kg-extract-rows**: पंक्तियाँ उत्पन्न करता है, ट्रिपल नहीं, अलग उत्पत्ति मॉडल।
|
||||
मॉडल।
|
||||
**क्वेरी-टाइम प्रोवेनेंस** (`urn:graph:retrieval`): एक अलग विषय,
|
||||
पहले से ही एक अलग पैटर्न का उपयोग करता है (प्रश्न/अन्वेषण/ध्यान/संश्लेषण)।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**दस्तावेज़/पृष्ठ/खंड प्रोवेनेंस** (पीडीएफ डिकोडर, चंकर): पहले से ही उपयोग करता है
|
||||
`derived_entity_triples()` जो प्रति-एंटिटी है, प्रति-ट्रिपल नहीं - कोई
|
||||
अनावश्यकता समस्या नहीं।
|
||||
|
||||
## कार्यान्वयन संबंधी टिप्पणियाँ
|
||||
|
||||
### प्रोसेसर लूप का पुनर्गठन
|
||||
|
||||
पहले (प्रत्येक त्रिक के लिए, संबंधों में):
|
||||
```python
|
||||
for rel in rels:
|
||||
# ... build relationship_triple ...
|
||||
stmt_uri = statement_uri()
|
||||
prov_triples = triple_provenance_triples(
|
||||
stmt_uri=stmt_uri,
|
||||
extracted_triple=relationship_triple,
|
||||
...
|
||||
)
|
||||
triples.extend(set_graph(prov_triples, GRAPH_SOURCE))
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
(उपग्राफ के बाद):
|
||||
=======
|
||||
(उप-ग्राफ के बाद):
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
```python
|
||||
sg_uri = subgraph_uri()
|
||||
|
||||
for rel in rels:
|
||||
# ... build relationship_triple ...
|
||||
extracted_triples.append(relationship_triple)
|
||||
|
||||
prov_triples = subgraph_provenance_triples(
|
||||
subgraph_uri=sg_uri,
|
||||
extracted_triples=extracted_triples,
|
||||
chunk_uri=chunk_uri,
|
||||
component_name=default_ident,
|
||||
component_version=COMPONENT_VERSION,
|
||||
llm_model=llm_model,
|
||||
ontology_uri=ontology_uri,
|
||||
)
|
||||
triples.extend(set_graph(prov_triples, GRAPH_SOURCE))
|
||||
```
|
||||
|
||||
### नया सहायक हस्ताक्षर
|
||||
|
||||
```python
|
||||
def subgraph_provenance_triples(
|
||||
subgraph_uri: str,
|
||||
extracted_triples: List[Triple],
|
||||
chunk_uri: str,
|
||||
component_name: str,
|
||||
component_version: str,
|
||||
llm_model: Optional[str] = None,
|
||||
ontology_uri: Optional[str] = None,
|
||||
timestamp: Optional[str] = None,
|
||||
) -> List[Triple]:
|
||||
"""
|
||||
Build provenance triples for a subgraph of extracted knowledge.
|
||||
|
||||
Creates:
|
||||
- tg:contains link for each extracted triple (RDF-star quoted)
|
||||
- One prov:wasDerivedFrom link to source chunk
|
||||
- One activity with agent metadata
|
||||
"""
|
||||
```
|
||||
|
||||
### महत्वपूर्ण परिवर्तन
|
||||
|
||||
<<<<<<< HEAD
|
||||
यह उत्पत्ति मॉडल में एक महत्वपूर्ण बदलाव है। उत्पत्ति (प्रोवेनेंस) का
|
||||
जारी किया गया है, इसलिए माइग्रेशन की आवश्यकता नहीं है। पुराना `tg:reifies` /
|
||||
`statement_uri` कोड पूरी तरह से हटाया जा सकता है।
|
||||
=======
|
||||
यह प्रामाणिकता मॉडल में एक महत्वपूर्ण बदलाव है। प्रामाणिकता अभी तक जारी नहीं की गई है, इसलिए किसी माइग्रेशन की आवश्यकता नहीं है। पुराना ⟦CODE_0⟧ / ⟦CODE_0⟧ कोड पूरी तरह से हटाया जा सकता है।
|
||||
यह प्रामाणिकता मॉडल में एक महत्वपूर्ण बदलाव है। प्रामाणिकता अभी तक जारी नहीं की गई है, इसलिए किसी माइग्रेशन की आवश्यकता नहीं है। पुराना `tg:reifies` / `tg:reifies` कोड पूरी तरह से हटाया जा सकता है।
|
||||
यह प्रामाणिकता मॉडल में एक महत्वपूर्ण बदलाव है। प्रामाणिकता अभी तक जारी नहीं की गई है, इसलिए किसी माइग्रेशन की आवश्यकता नहीं है। पुराना `statement_uri` / `statement_uri` कोड पूरी तरह से हटाया जा सकता है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
767
docs/tech-specs/hi/extraction-time-provenance.hi.md
Normal file
767
docs/tech-specs/hi/extraction-time-provenance.hi.md
Normal file
|
|
@ -0,0 +1,767 @@
|
|||
---
|
||||
layout: default
|
||||
title: "निष्कर्षण-समय का प्रमाण: स्रोत परत"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# निष्कर्षण-समय का प्रमाण: स्रोत परत
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह दस्तावेज़ भविष्य के विनिर्देशन कार्य के लिए निष्कर्षण-समय के प्रमाण पर नोट्स एकत्र करता है। निष्कर्षण-समय का प्रमाण "स्रोत परत" को रिकॉर्ड करता है - डेटा मूल रूप से कहाँ से आया, इसे कैसे निकाला और रूपांतरित किया गया।
|
||||
|
||||
यह क्वेरी-समय के प्रमाण (देखें `query-time-provenance.md`) से अलग है, जो एजेंट तर्क को रिकॉर्ड करता है।
|
||||
|
||||
## समस्या विवरण
|
||||
|
||||
### वर्तमान कार्यान्वयन
|
||||
|
||||
वर्तमान में, प्रमाण इस प्रकार काम करता है:
|
||||
दस्तावेज़ मेटाडेटा को ज्ञान ग्राफ में RDF ट्रिपल के रूप में संग्रहीत किया जाता है
|
||||
एक दस्तावेज़ आईडी मेटाडेटा को दस्तावेज़ से जोड़ती है, इसलिए दस्तावेज़ ग्राफ में एक नोड के रूप में दिखाई देता है
|
||||
जब दस्तावेज़ों से किनारे (संबंध/तथ्य) निकाले जाते हैं, तो एक `subjectOf` संबंध निकाले गए किनारे को स्रोत दस्तावेज़ से जोड़ता है
|
||||
|
||||
### वर्तमान दृष्टिकोण की समस्याएं
|
||||
|
||||
<<<<<<< HEAD
|
||||
1. **दोहरा मेटाडेटा लोडिंग:** दस्तावेज़ मेटाडेटा को प्रत्येक दस्तावेज़ से निकाले गए ट्रिपल बैच के साथ बार-बार बंडल किया जाता है और लोड किया जाता है। यह अनावश्यक और दोहराव वाला है - समान मेटाडेटा प्रत्येक निष्कर्षण आउटपुट के साथ पेलोड के रूप में यात्रा करता है।
|
||||
|
||||
2. **उथला प्रमाण:** वर्तमान `subjectOf` संबंध केवल तथ्यों को सीधे शीर्ष-स्तरीय दस्तावेज़ से जोड़ता है। परिवर्तन श्रृंखला में कोई दृश्यता नहीं है - तथ्य किस पृष्ठ से आया, किस भाग से, किस निष्कर्षण विधि का उपयोग किया गया था।
|
||||
=======
|
||||
1. **दोहरा मेटाडेटा लोडिंग:** दस्तावेज़ मेटाडेटा को प्रत्येक दस्तावेज़ से निकाले गए ट्रिपल के प्रत्येक बैच के साथ बार-बार बंडल किया जाता है और लोड किया जाता है। यह अनावश्यक और दोहराव वाला है - समान मेटाडेटा प्रत्येक निष्कर्षण आउटपुट के साथ पेलोड के रूप में यात्रा करता है।
|
||||
|
||||
2. **उथला प्रमाण:** वर्तमान `subjectOf` संबंध केवल तथ्यों को सीधे शीर्ष-स्तरीय दस्तावेज़ से जोड़ता है। परिवर्तन श्रृंखला में कोई दृश्यता नहीं है - तथ्य किस पृष्ठ से आया, किस खंड से, किस निष्कर्षण विधि का उपयोग किया गया था।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
### वांछित स्थिति
|
||||
|
||||
1. **मेटाडेटा को एक बार लोड करें:** दस्तावेज़ मेटाडेटा को एक बार लोड किया जाना चाहिए और शीर्ष-स्तरीय दस्तावेज़ नोड से जोड़ा जाना चाहिए, न कि प्रत्येक ट्रिपल बैच के साथ दोहराया जाना चाहिए।
|
||||
|
||||
<<<<<<< HEAD
|
||||
2. **समृद्ध प्रमाण DAG:** स्रोत दस्तावेज़ से सभी मध्यवर्ती कलाकृतियों से लेकर निकाले गए तथ्यों तक, संपूर्ण परिवर्तन श्रृंखला को कैप्चर करें। उदाहरण के लिए, एक PDF दस्तावेज़ रूपांतरण:
|
||||
=======
|
||||
2. **समृद्ध प्रमाण DAG:** स्रोत दस्तावेज़ से सभी मध्यवर्ती कलाकृतियों से लेकर निकाले गए तथ्यों तक, पूर्ण परिवर्तन श्रृंखला को कैप्चर करें। उदाहरण के लिए, एक PDF दस्तावेज़ रूपांतरण:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
```
|
||||
PDF file (source document with metadata)
|
||||
→ Page 1 (decoded text)
|
||||
→ Chunk 1
|
||||
→ Extracted edge/fact (via subjectOf)
|
||||
→ Extracted edge/fact
|
||||
→ Chunk 2
|
||||
→ Extracted edge/fact
|
||||
→ Page 2
|
||||
→ Chunk 3
|
||||
→ ...
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
3. **एकीकृत भंडारण:** उत्पत्ति (provenance) DAG को उसी ज्ञान ग्राफ में संग्रहीत किया जाता है जैसे कि निकाले गए ज्ञान को। यह उत्पत्ति को ज्ञान की तरह ही क्वेरी करने की अनुमति देता है - किसी भी तथ्य से लेकर उसके सटीक स्रोत स्थान तक, श्रृंखला में किनारों का पालन करके।
|
||||
|
||||
4. **स्थिर आईडी:** प्रत्येक मध्यवर्ती कलाकृति (पेज, चंक) का ग्राफ में एक नोड के रूप में एक स्थिर आईडी होता है।
|
||||
|
||||
5. **पैरेंट-चाइल्ड लिंकिंग:** व्युत्पन्न दस्तावेज़ों को सुसंगत संबंध प्रकारों का उपयोग करके शीर्ष-स्तरीय स्रोत दस्तावेज़ तक उनके माता-पिता से जोड़ा जाता है।
|
||||
=======
|
||||
3. **एकीकृत भंडारण:** उत्पत्ति (provenance) DAG को उसी ज्ञान ग्राफ में संग्रहीत किया जाता है जैसे कि निकाले गए ज्ञान को। यह उत्पत्ति को ज्ञान की तरह ही क्वेरी करने की अनुमति देता है - किसी भी तथ्य से लेकर उसके सटीक स्रोत स्थान तक, श्रृंखला में वापस किनारों का पालन करना।
|
||||
|
||||
4. **स्थिर आईडी:** प्रत्येक मध्यवर्ती कलाकृति (पेज, चंक) का ग्राफ में एक नोड के रूप में एक स्थिर आईडी होता है।
|
||||
|
||||
5. **माता-पिता-बच्चे संबंध:** व्युत्पन्न दस्तावेज़ों को सुसंगत संबंध प्रकारों का उपयोग करके शीर्ष-स्तरीय स्रोत दस्तावेज़ तक उनके माता-पिता से जोड़ा जाता है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
6. **सटीक तथ्यattribution:** निकाले गए किनारों पर `subjectOf` संबंध तत्काल माता-पिता (चंक) की ओर इशारा करता है, न कि शीर्ष-स्तरीय दस्तावेज़ की ओर। पूर्ण उत्पत्ति को DAG के माध्यम से ऊपर की ओर ट्रैवर्स करके पुनर्प्राप्त किया जाता है।
|
||||
|
||||
## उपयोग के मामले
|
||||
|
||||
### UC1: GraphRAG प्रतिक्रियाओं में स्रोत attribution
|
||||
|
||||
<<<<<<< HEAD
|
||||
**परिदृश्य:** एक उपयोगकर्ता GraphRAG क्वेरी चलाता है और एजेंट से एक प्रतिक्रिया प्राप्त करता है।
|
||||
|
||||
**प्रवाह:**
|
||||
1. उपयोगकर्ता GraphRAG एजेंट को एक क्वेरी सबमिट करता है
|
||||
2. एजेंट प्रतिक्रिया तैयार करने के लिए ज्ञान ग्राफ से प्रासंगिक तथ्यों को पुनर्प्राप्त करता है
|
||||
3. क्वेरी-टाइम provenance विनिर्देश के अनुसार, एजेंट उन तथ्यों की रिपोर्ट करता है जिन्होंने प्रतिक्रिया में योगदान दिया
|
||||
4. प्रत्येक तथ्य provenance DAG के माध्यम से अपने स्रोत चंक से जुड़ा होता है
|
||||
5. चंक पृष्ठों से जुड़ते हैं, पृष्ठ स्रोत दस्तावेज़ों से जुड़ते हैं
|
||||
|
||||
**उपयोगकर्ता अनुभव परिणाम:** इंटरफ़ेस LLM प्रतिक्रिया के साथ स्रोत attribution प्रदर्शित करता है। उपयोगकर्ता:
|
||||
प्रतिक्रिया का समर्थन करने वाले तथ्यों को देख सकते हैं
|
||||
तथ्यों → चंक → पृष्ठ → दस्तावेज़ से ड्रिल डाउन कर सकते हैं
|
||||
दावों को सत्यापित करने के लिए मूल स्रोत दस्तावेज़ों की समीक्षा कर सकते हैं
|
||||
यह समझ सकते हैं कि एक तथ्य दस्तावेज़ में कहाँ से (किस पृष्ठ, किस अनुभाग से) उत्पन्न हुआ था
|
||||
=======
|
||||
**परिदृश्य:** एक उपयोगकर्ता GraphRAG क्वेरी चलाता है और एजेंट से प्रतिक्रिया प्राप्त करता है।
|
||||
|
||||
**प्रक्रिया:**
|
||||
1. उपयोगकर्ता GraphRAG एजेंट को एक क्वेरी सबमिट करता है।
|
||||
2. एजेंट प्रतिक्रिया तैयार करने के लिए ज्ञान ग्राफ से प्रासंगिक तथ्यों को पुनः प्राप्त करता है।
|
||||
3. क्वेरी-समय provenance विनिर्देश के अनुसार, एजेंट उन तथ्यों की रिपोर्ट करता है जिन्होंने प्रतिक्रिया में योगदान दिया।
|
||||
4. प्रत्येक तथ्य अपने स्रोत चंक से provenance DAG के माध्यम से जुड़ा होता है।
|
||||
5. चंक पृष्ठों से जुड़े होते हैं, पृष्ठ स्रोत दस्तावेज़ों से जुड़े होते हैं।
|
||||
|
||||
**उपयोगकर्ता अनुभव परिणाम:** इंटरफ़ेस LLM प्रतिक्रिया के साथ स्रोत attribution प्रदर्शित करता है। उपयोगकर्ता निम्न कार्य कर सकते हैं:
|
||||
प्रतिक्रिया का समर्थन करने वाले तथ्यों को देखें।
|
||||
तथ्यों → चंक → पृष्ठ → दस्तावेज़ से नीचे ड्रिल करें।
|
||||
दावों को सत्यापित करने के लिए मूल स्रोत दस्तावेज़ों की समीक्षा करें।
|
||||
समझें कि एक तथ्य दस्तावेज़ में (किस पृष्ठ पर, किस अनुभाग में) से उत्पन्न हुआ था।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**मूल्य:** उपयोगकर्ता AI-जनित प्रतिक्रियाओं को प्राथमिक स्रोतों के विरुद्ध सत्यापित कर सकते हैं, जिससे विश्वास बढ़ता है और तथ्य-जांच सक्षम होती है।
|
||||
|
||||
### UC2: निष्कर्षण गुणवत्ता का डिबगिंग
|
||||
|
||||
एक तथ्य गलत दिखता है। मूल पाठ देखने के लिए चंक → पृष्ठ → दस्तावेज़ के माध्यम से वापस ट्रेस करें। क्या यह एक खराब निष्कर्षण था, या क्या स्रोत स्वयं गलत था?
|
||||
|
||||
### UC3: वृद्धिशील पुन: निष्कर्षण
|
||||
|
||||
<<<<<<< HEAD
|
||||
स्रोत दस्तावेज़ अपडेट किया गया है। किन चंक/तथ्यों को इससे व्युत्पन्न किया गया था? केवल उन चंक/तथ्यों को अमान्य करें और पुन: उत्पन्न करें, न कि सब कुछ को पुन: संसाधित करें।
|
||||
=======
|
||||
स्रोत दस्तावेज़ अपडेट किया गया है। किन चंक/तथ्यों को इससे व्युत्पन्न किया गया था? केवल उन चंक को अमान्य करें और पुन: उत्पन्न करें, न कि सब कुछ को फिर से संसाधित करें।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
### UC4: डेटा हटाना / भुलाए जाने का अधिकार
|
||||
|
||||
एक स्रोत दस्तावेज़ को हटाया जाना चाहिए (GDPR, कानूनी, आदि)। सभी व्युत्पन्न तथ्यों को खोजने और हटाने के लिए DAG को पार करें।
|
||||
|
||||
### UC5: संघर्ष समाधान
|
||||
|
||||
दो तथ्य एक-दूसरे का खंडन करते हैं। कारण को समझने और यह तय करने के लिए कि किस पर भरोसा करना है (अधिक आधिकारिक स्रोत, अधिक हालिया, आदि), दोनों को उनके स्रोतों तक वापस ट्रेस करें।
|
||||
|
||||
### UC6: स्रोत प्राधिकरण भार
|
||||
|
||||
कुछ स्रोत दूसरों की तुलना में अधिक आधिकारिक होते हैं। तथ्यों को उनके मूल दस्तावेज़ों के प्राधिकरण/गुणवत्ता के आधार पर भारित या फ़िल्टर किया जा सकता है।
|
||||
|
||||
### UC7: निष्कर्षण पाइपलाइन तुलना
|
||||
|
||||
<<<<<<< HEAD
|
||||
विभिन्न निष्कर्षण विधियों/संस्करणों से आउटपुट की तुलना करें। किस निष्कर्षण ने समान स्रोत से बेहतर तथ्य उत्पन्न किए?
|
||||
=======
|
||||
विभिन्न निष्कर्षण विधियों/संस्करणों से प्राप्त परिणामों की तुलना करें। किस निष्कर्षण ने समान स्रोत से बेहतर तथ्य उत्पन्न किए?
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## एकीकरण बिंदु
|
||||
|
||||
### लाइब्रेरियन
|
||||
|
||||
लाइब्रेरियन घटक पहले से ही अद्वितीय दस्तावेज़ आईडी के साथ दस्तावेज़ भंडारण प्रदान करता है। प्रोवेनेंस सिस्टम इस मौजूदा बुनियादी ढांचे के साथ एकीकृत होता है।
|
||||
|
||||
#### मौजूदा क्षमताएं (पहले से लागू)
|
||||
|
||||
**पैरेंट-चाइल्ड दस्तावेज़ लिंकिंग:**
|
||||
`parent_id` फ़ील्ड `DocumentMetadata` में - चाइल्ड को पैरेंट दस्तावेज़ से जोड़ता है
|
||||
`document_type` फ़ील्ड - मान: `"source"` (मूल) या `"extracted"` (व्युत्पन्न)
|
||||
`add-child-document` एपीआई - स्वचालित `document_type = "extracted"` के साथ चाइल्ड दस्तावेज़ बनाता है
|
||||
`list-children` एपीआई - एक पैरेंट दस्तावेज़ के सभी चाइल्ड को पुनः प्राप्त करता है
|
||||
<<<<<<< HEAD
|
||||
कैस्केड डिलीशन - एक पैरेंट को हटाने से स्वचालित रूप से सभी चाइल्ड दस्तावेज़ हटा दिए जाते हैं
|
||||
=======
|
||||
कैस्केड डिलीशन - एक पैरेंट को हटाने से स्वचालित रूप से सभी चाइल्ड दस्तावेज़ हट जाते हैं
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**दस्तावेज़ पहचान:**
|
||||
दस्तावेज़ आईडी क्लाइंट द्वारा निर्दिष्ट हैं (स्वचालित रूप से उत्पन्न नहीं)
|
||||
दस्तावेज़ों को कैसेंड्रा में समग्र `(user, document_id)` द्वारा कुंजीबद्ध किया जाता है
|
||||
ऑब्जेक्ट आईडी (UUID) आंतरिक रूप से ब्लब स्टोरेज के लिए उत्पन्न होते हैं
|
||||
|
||||
**मेटाडेटा समर्थन:**
|
||||
`metadata: list[Triple]` फ़ील्ड - संरचित मेटाडेटा के लिए आरडीएफ ट्रिपल
|
||||
`title`, `comments`, `tags` - बुनियादी दस्तावेज़ मेटाडेटा
|
||||
`time` - टाइमस्टैम्प, `kind` - एमआईएमई प्रकार
|
||||
|
||||
**भंडारण आर्किटेक्चर:**
|
||||
मेटाडेटा कैसेंड्रा में संग्रहीत है (`librarian` कीस्पेस, `document` टेबल)
|
||||
सामग्री MinIO/S3 ब्लब स्टोरेज में संग्रहीत है (`library` बकेट)
|
||||
<<<<<<< HEAD
|
||||
स्मार्ट सामग्री वितरण: 2MB से कम दस्तावेज़ एम्बेडेड हैं, बड़े दस्तावेज़ स्ट्रीम किए जाते हैं
|
||||
=======
|
||||
स्मार्ट सामग्री वितरण: 2MB से छोटे दस्तावेज़ एम्बेडेड होते हैं, बड़े दस्तावेज़ स्ट्रीम किए जाते हैं
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
#### मुख्य फाइलें
|
||||
|
||||
`trustgraph-flow/trustgraph/librarian/librarian.py` - मुख्य लाइब्रेरियन ऑपरेशन
|
||||
`trustgraph-flow/trustgraph/librarian/service.py` - सर्विस प्रोसेसर, दस्तावेज़ लोडिंग
|
||||
`trustgraph-flow/trustgraph/tables/library.py` - कैसेंड्रा टेबल स्टोर
|
||||
`trustgraph-base/trustgraph/schema/services/library.py` - स्कीमा परिभाषाएं
|
||||
|
||||
#### संबोधित करने योग्य कमियां
|
||||
|
||||
लाइब्रेरियन में बिल्डिंग ब्लॉक्स हैं लेकिन वर्तमान में:
|
||||
1. पैरेंट-चाइल्ड लिंकिंग एक स्तर गहरा है - मल्टी-लेवल डीएजी ट्रैवर्सल हेल्पर नहीं हैं
|
||||
2. कोई मानक संबंध प्रकार शब्दावली नहीं (जैसे, `derivedFrom`, `extractedFrom`)
|
||||
3. प्रोवेनेंस मेटाडेटा (निष्कर्षण विधि, आत्मविश्वास, चंक स्थिति) मानकीकृत नहीं है
|
||||
4. तथ्य से स्रोत तक संपूर्ण प्रोवेनेंस श्रृंखला को पार करने के लिए कोई क्वेरी एपीआई नहीं है
|
||||
|
||||
## एंड-टू-एंड फ्लो डिज़ाइन
|
||||
|
||||
पाइपलाइन में प्रत्येक प्रोसेसर एक सुसंगत पैटर्न का पालन करता है:
|
||||
अपस्ट्रीम से दस्तावेज़ आईडी प्राप्त करें
|
||||
लाइब्रेरियन से सामग्री प्राप्त करें
|
||||
चाइल्ड आर्टिफैक्ट उत्पन्न करें
|
||||
प्रत्येक चाइल्ड के लिए: लाइब्रेरियन में सहेजें, ग्राफ में एज उत्सर्जित करें, आईडी को डाउनस्ट्रीम पर अग्रेषित करें
|
||||
|
||||
### प्रोसेसिंग फ्लो
|
||||
|
||||
दस्तावेज़ के प्रकार के आधार पर दो फ्लो हैं:
|
||||
|
||||
#### पीडीएफ दस्तावेज़ फ्लो
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Librarian (initiate processing) │
|
||||
│ 1. Emit root document metadata to knowledge graph (once) │
|
||||
│ 2. Send root document ID to PDF extractor │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ PDF Extractor (per page) │
|
||||
│ 1. Fetch PDF content from librarian using document ID │
|
||||
│ 2. Extract pages as text │
|
||||
│ 3. For each page: │
|
||||
│ a. Save page as child document in librarian (parent = root doc) │
|
||||
│ b. Emit parent-child edge to knowledge graph │
|
||||
│ c. Send page document ID to chunker │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Chunker (per chunk) │
|
||||
│ 1. Fetch page content from librarian using document ID │
|
||||
│ 2. Split text into chunks │
|
||||
│ 3. For each chunk: │
|
||||
│ a. Save chunk as child document in librarian (parent = page) │
|
||||
│ b. Emit parent-child edge to knowledge graph │
|
||||
│ c. Send chunk document ID + chunk content to next processor │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
|
||||
Post-chunker optimization: messages carry both
|
||||
chunk ID (for provenance) and content (to avoid
|
||||
librarian round-trip). Chunks are small (2-4KB).
|
||||
─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Knowledge Extractor (per chunk) │
|
||||
│ 1. Receive chunk ID + content directly (no librarian fetch needed) │
|
||||
│ 2. Extract facts/triples and embeddings from chunk content │
|
||||
│ 3. For each triple: │
|
||||
│ a. Emit triple to knowledge graph │
|
||||
│ b. Emit reified edge linking triple → chunk ID (edge pointing │
|
||||
│ to edge - first use of reification support) │
|
||||
│ 4. For each embedding: │
|
||||
│ a. Emit embedding with its entity ID │
|
||||
│ b. Link entity ID → chunk ID in knowledge graph │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### पाठ दस्तावेज़ प्रवाह
|
||||
|
||||
पाठ दस्तावेज़ पीडीएफ एक्सट्रैक्टर को छोड़ देते हैं और सीधे चंकर पर जाते हैं:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Librarian (initiate processing) │
|
||||
│ 1. Emit root document metadata to knowledge graph (once) │
|
||||
│ 2. Send root document ID directly to chunker (skip PDF extractor) │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Chunker (per chunk) │
|
||||
│ 1. Fetch text content from librarian using document ID │
|
||||
│ 2. Split text into chunks │
|
||||
│ 3. For each chunk: │
|
||||
│ a. Save chunk as child document in librarian (parent = root doc) │
|
||||
│ b. Emit parent-child edge to knowledge graph │
|
||||
│ c. Send chunk document ID + chunk content to next processor │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Knowledge Extractor │
|
||||
│ (same as PDF flow) │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
परिणामी निर्देशित एसाइक्लिक ग्राफ (DAG) एक स्तर छोटा होता है:
|
||||
=======
|
||||
परिणामी DAG एक स्तर छोटा होता है:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
```
|
||||
PDF: Document → Pages → Chunks → Triples/Embeddings
|
||||
Text: Document → Chunks → Triples/Embeddings
|
||||
```
|
||||
|
||||
डिज़ाइन दोनों को समायोजित करता है क्योंकि चंकर अपने इनपुट को सामान्य रूप से संसाधित करता है - यह जो भी दस्तावेज़ आईडी प्राप्त करता है, उसे पैरेंट के रूप में उपयोग करता है, चाहे वह स्रोत दस्तावेज़ हो या पृष्ठ।
|
||||
|
||||
### मेटाडेटा स्कीमा (PROV-O)
|
||||
|
||||
प्रामाणिकता मेटाडेटा W3C PROV-O ऑन्टोलॉजी का उपयोग करता है। यह एक मानक शब्दावली प्रदान करता है और निष्कर्षण आउटपुट के भविष्य के हस्ताक्षर/प्रमाणीकरण को सक्षम बनाता है।
|
||||
|
||||
#### PROV-O मुख्य अवधारणाएँ
|
||||
|
||||
| PROV-O प्रकार | ट्रस्टग्राफ उपयोग |
|
||||
|-------------|------------------|
|
||||
| `prov:Entity` | दस्तावेज़, पृष्ठ, चंक, ट्रिपल, एम्बेडिंग |
|
||||
| `prov:Activity` | निष्कर्षण कार्यों के उदाहरण |
|
||||
| `prov:Agent` | टीजी घटक (पीडीएफ एक्सट्रैक्टर, चंकर, आदि) संस्करणों के साथ |
|
||||
|
||||
#### PROV-O संबंध
|
||||
|
||||
| विधेय | अर्थ | उदाहरण |
|
||||
|-----------|---------|---------|
|
||||
<<<<<<< HEAD
|
||||
| `prov:wasDerivedFrom` | एक इकाई से व्युत्पन्न अन्य इकाई | पृष्ठ दस्तावेज़ से व्युत्पन्न था |
|
||||
| `prov:wasGeneratedBy` | एक गतिविधि द्वारा उत्पन्न इकाई | पृष्ठ पीडीएफ निष्कर्षण गतिविधि द्वारा उत्पन्न किया गया था |
|
||||
| `prov:used` | गतिविधि ने एक इकाई को इनपुट के रूप में उपयोग किया | पीडीएफ निष्कर्षण गतिविधि ने दस्तावेज़ का उपयोग किया |
|
||||
| `prov:wasAssociatedWith` | एक एजेंट द्वारा की गई गतिविधि | पीडीएफ निष्कर्षण गतिविधि tg:पीडीएफएक्सट्रैक्टर से जुड़ी थी |
|
||||
=======
|
||||
| `prov:wasDerivedFrom` | एक इकाई किसी अन्य इकाई से प्राप्त हुई | पृष्ठ दस्तावेज़ से प्राप्त हुआ |
|
||||
| `prov:wasGeneratedBy` | एक इकाई एक गतिविधि द्वारा उत्पन्न हुई | पृष्ठ पीडीएफ निष्कर्षण गतिविधि द्वारा उत्पन्न हुआ |
|
||||
| `prov:used` | एक गतिविधि ने एक इकाई को इनपुट के रूप में उपयोग किया | पीडीएफ निष्कर्षण गतिविधि ने दस्तावेज़ का उपयोग किया |
|
||||
| `prov:wasAssociatedWith` | एक गतिविधि एक एजेंट द्वारा की गई | पीडीएफ निष्कर्षण गतिविधि tg:पीडीएफएक्सट्रैक्टर से जुड़ी थी |
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
#### प्रत्येक स्तर पर मेटाडेटा
|
||||
|
||||
**स्रोत दस्तावेज़ (लाइब्रेरियन द्वारा उत्सर्जित):**
|
||||
```
|
||||
doc:123 a prov:Entity .
|
||||
doc:123 dc:title "Research Paper" .
|
||||
doc:123 dc:source <https://example.com/paper.pdf> .
|
||||
doc:123 dc:date "2024-01-15" .
|
||||
doc:123 dc:creator "Author Name" .
|
||||
doc:123 tg:pageCount 42 .
|
||||
doc:123 tg:mimeType "application/pdf" .
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
**पृष्ठ (पीडीएफ एक्सट्रैक्टर द्वारा उत्सर्जित):**
|
||||
=======
|
||||
**पृष्ठ (पीडीएफ एक्सट्रैक्टर द्वारा उत्पन्न):**
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
```
|
||||
page:123-1 a prov:Entity .
|
||||
page:123-1 prov:wasDerivedFrom doc:123 .
|
||||
page:123-1 prov:wasGeneratedBy activity:pdf-extract-456 .
|
||||
page:123-1 tg:pageNumber 1 .
|
||||
|
||||
activity:pdf-extract-456 a prov:Activity .
|
||||
activity:pdf-extract-456 prov:used doc:123 .
|
||||
activity:pdf-extract-456 prov:wasAssociatedWith tg:PDFExtractor .
|
||||
activity:pdf-extract-456 tg:componentVersion "1.2.3" .
|
||||
activity:pdf-extract-456 prov:startedAtTime "2024-01-15T10:30:00Z" .
|
||||
```
|
||||
|
||||
**खंड (चंकर द्वारा उत्सर्जित):**
|
||||
```
|
||||
chunk:123-1-1 a prov:Entity .
|
||||
chunk:123-1-1 prov:wasDerivedFrom page:123-1 .
|
||||
chunk:123-1-1 prov:wasGeneratedBy activity:chunk-789 .
|
||||
chunk:123-1-1 tg:chunkIndex 1 .
|
||||
chunk:123-1-1 tg:charOffset 0 .
|
||||
chunk:123-1-1 tg:charLength 2048 .
|
||||
|
||||
activity:chunk-789 a prov:Activity .
|
||||
activity:chunk-789 prov:used page:123-1 .
|
||||
activity:chunk-789 prov:wasAssociatedWith tg:Chunker .
|
||||
activity:chunk-789 tg:componentVersion "1.0.0" .
|
||||
activity:chunk-789 tg:chunkSize 2048 .
|
||||
activity:chunk-789 tg:chunkOverlap 200 .
|
||||
```
|
||||
|
||||
**ट्रिपल (नॉलेज एक्सट्रैक्टर द्वारा उत्सर्जित):**
|
||||
```
|
||||
# The extracted triple (edge)
|
||||
entity:JohnSmith rel:worksAt entity:AcmeCorp .
|
||||
|
||||
# Subgraph containing the extracted triples
|
||||
subgraph:001 tg:contains <<entity:JohnSmith rel:worksAt entity:AcmeCorp>> .
|
||||
subgraph:001 prov:wasDerivedFrom chunk:123-1-1 .
|
||||
subgraph:001 prov:wasGeneratedBy activity:extract-999 .
|
||||
|
||||
activity:extract-999 a prov:Activity .
|
||||
activity:extract-999 prov:used chunk:123-1-1 .
|
||||
activity:extract-999 prov:wasAssociatedWith tg:KnowledgeExtractor .
|
||||
activity:extract-999 tg:componentVersion "2.1.0" .
|
||||
activity:extract-999 tg:llmModel "claude-3" .
|
||||
activity:extract-999 tg:ontology <http://example.org/ontologies/business-v1> .
|
||||
```
|
||||
|
||||
**एम्बेडिंग (वेक्टर स्टोर में संग्रहीत, ट्रिपल स्टोर में नहीं):**
|
||||
|
||||
एम्बेडिंग को मेटाडेटा के साथ वेक्टर स्टोर में संग्रहीत किया जाता है, न कि आरडीएफ ट्रिपल के रूप में। प्रत्येक एम्बेडिंग रिकॉर्ड में निम्नलिखित शामिल हैं:
|
||||
|
||||
| फ़ील्ड | विवरण | उदाहरण |
|
||||
|-------|-------------|---------|
|
||||
| वेक्टर | एम्बेडिंग वेक्टर | [0.123, -0.456, ...] |
|
||||
| एंटिटी | नोड यूआरआई जिसे एम्बेडिंग दर्शाता है | `entity:JohnSmith` |
|
||||
| चंक_आईडी | स्रोत चंक (उत्पत्ति) | `chunk:123-1-1` |
|
||||
| मॉडल | उपयोग किया गया एम्बेडिंग मॉडल | `text-embedding-ada-002` |
|
||||
| कंपोनेंट_वर्जन | टीजी एम्बेडर संस्करण | `1.0.0` |
|
||||
|
||||
`entity` फ़ील्ड एम्बेडिंग को नॉलेज ग्राफ (नोड यूआरआई) से जोड़ता है। `chunk_id` फ़ील्ड स्रोत चंक तक उत्पत्ति जानकारी प्रदान करता है, जिससे मूल दस्तावेज़ तक डीएजी (DAG) के माध्यम से ट्रैवर्स करना संभव हो जाता है।
|
||||
|
||||
#### ट्रस्टग्राफ नेमस्पेस एक्सटेंशन
|
||||
|
||||
<<<<<<< HEAD
|
||||
निष्कर्षण-विशिष्ट मेटाडेटा के लिए `tg:` नेमस्पेस के अंतर्गत कस्टम प्रेडिकेट:
|
||||
=======
|
||||
निष्कर्षण-विशिष्ट मेटाडेटा के लिए `tg:` नेमस्पेस के तहत कस्टम प्रेडिकेट:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
| प्रेडिकेट | डोमेन | विवरण |
|
||||
|-----------|--------|-------------|
|
||||
| `tg:contains` | सबग्राफ | इस निष्कर्षण सबग्राफ में निहित ट्रिपल की ओर इंगित करता है |
|
||||
| `tg:pageCount` | दस्तावेज़ | स्रोत दस्तावेज़ में पृष्ठों की कुल संख्या |
|
||||
| `tg:mimeType` | दस्तावेज़ | स्रोत दस्तावेज़ का एमआईएमई (MIME) प्रकार |
|
||||
| `tg:pageNumber` | पृष्ठ | स्रोत दस्तावेज़ में पृष्ठ संख्या |
|
||||
| `tg:chunkIndex` | चंक | मूल में चंक का इंडेक्स |
|
||||
| `tg:charOffset` | चंक | मूल पाठ में कैरेक्टर ऑफसेट |
|
||||
| `tg:charLength` | चंक | कैरेक्टर में चंक की लंबाई |
|
||||
| `tg:chunkSize` | गतिविधि | कॉन्फ़िगर किया गया चंक आकार |
|
||||
<<<<<<< HEAD
|
||||
| `tg:chunkOverlap` | गतिविधि | चंक के बीच कॉन्फ़िगर किया गया ओवरलैप |
|
||||
| `tg:componentVersion` | गतिविधि | टीजी घटक का संस्करण |
|
||||
| `tg:llmModel` | गतिविधि | निष्कर्षण के लिए उपयोग किया गया एलएलएम (LLM) |
|
||||
| `tg:ontology` | गतिविधि | निष्कर्षण का मार्गदर्शन करने के लिए उपयोग किया गया ऑन्टोलॉजी यूआरआई |
|
||||
=======
|
||||
| `tg:chunkOverlap` | गतिविधि | चंक्स के बीच कॉन्फ़िगर किया गया ओवरलैप |
|
||||
| `tg:componentVersion` | गतिविधि | टीजी घटक का संस्करण |
|
||||
| `tg:llmModel` | गतिविधि | निष्कर्षण के लिए उपयोग किया गया एलएलएम (LLM) |
|
||||
| `tg:ontology` | गतिविधि | निष्कर्षण को निर्देशित करने के लिए उपयोग किया गया ऑन्टोलॉजी यूआरआई |
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
| `tg:embeddingModel` | गतिविधि | एम्बेडिंग के लिए उपयोग किया गया मॉडल |
|
||||
| `tg:sourceText` | स्टेटमेंट | ट्रिपल से निकाले गए सटीक पाठ |
|
||||
| `tg:sourceCharOffset` | स्टेटमेंट | चंक के भीतर स्रोत पाठ की शुरुआत का कैरेक्टर ऑफसेट |
|
||||
| `tg:sourceCharLength` | स्टेटमेंट | कैरेक्टर में स्रोत पाठ की लंबाई |
|
||||
|
||||
#### शब्दावली बूटस्ट्रैप (प्रत्येक संग्रह के लिए)
|
||||
|
||||
नॉलेज ग्राफ ऑन्टोलॉजी-तटस्थ है और खाली अवस्था में शुरू होता है। पहली बार किसी संग्रह में पीआरओवी-ओ (PROV-O) उत्पत्ति डेटा लिखते समय, सभी क्लास और प्रेडिकेट के लिए आरडीएफ लेबल के साथ शब्दावली को बूटस्ट्रैप किया जाना चाहिए। यह प्रश्नों और यूआई (UI) में मानव-पठनीय प्रदर्शन सुनिश्चित करता है।
|
||||
|
||||
**पीआरओवी-ओ क्लास:**
|
||||
```
|
||||
prov:Entity rdfs:label "Entity" .
|
||||
prov:Activity rdfs:label "Activity" .
|
||||
prov:Agent rdfs:label "Agent" .
|
||||
```
|
||||
|
||||
**प्रोव-ओ विधेय:**
|
||||
```
|
||||
prov:wasDerivedFrom rdfs:label "was derived from" .
|
||||
prov:wasGeneratedBy rdfs:label "was generated by" .
|
||||
prov:used rdfs:label "used" .
|
||||
prov:wasAssociatedWith rdfs:label "was associated with" .
|
||||
prov:startedAtTime rdfs:label "started at" .
|
||||
```
|
||||
|
||||
**ट्रस्टग्राफ प्रेडिकेट्स:**
|
||||
```
|
||||
tg:contains rdfs:label "contains" .
|
||||
tg:pageCount rdfs:label "page count" .
|
||||
tg:mimeType rdfs:label "MIME type" .
|
||||
tg:pageNumber rdfs:label "page number" .
|
||||
tg:chunkIndex rdfs:label "chunk index" .
|
||||
tg:charOffset rdfs:label "character offset" .
|
||||
tg:charLength rdfs:label "character length" .
|
||||
tg:chunkSize rdfs:label "chunk size" .
|
||||
tg:chunkOverlap rdfs:label "chunk overlap" .
|
||||
tg:componentVersion rdfs:label "component version" .
|
||||
tg:llmModel rdfs:label "LLM model" .
|
||||
tg:ontology rdfs:label "ontology" .
|
||||
tg:embeddingModel rdfs:label "embedding model" .
|
||||
tg:sourceText rdfs:label "source text" .
|
||||
tg:sourceCharOffset rdfs:label "source character offset" .
|
||||
tg:sourceCharLength rdfs:label "source character length" .
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
**कार्यान्वयन नोट:** यह शब्दावली बूटस्ट्रैप आइडेंम्पोटेंट होना चाहिए - बिना डुप्लिकेट बनाए कई बार चलाने के लिए सुरक्षित। इसे किसी संग्रह में पहली बार दस्तावेज़ प्रसंस्करण के दौरान या एक अलग संग्रह आरंभीकरण चरण के रूप में ट्रिगर किया जा सकता है।
|
||||
|
||||
#### उप-खंड उत्पत्ति (आदर्श)
|
||||
|
||||
अधिक बारीक उत्पत्ति के लिए, यह महत्वपूर्ण होगा कि एक त्रिक को एक खंड के भीतर से ठीक कहाँ से निकाला गया था, इसका रिकॉर्ड रखा जाए। यह निम्नलिखित को सक्षम करता है:
|
||||
=======
|
||||
**कार्यान्वयन नोट:** यह शब्दावली बूटस्ट्रैप आइडेंम्पोटेंट होना चाहिए - डुप्लिकेट बनाए बिना कई बार चलाने के लिए सुरक्षित। इसे किसी संग्रह में पहली बार दस्तावेज़ प्रसंस्करण के दौरान या एक अलग संग्रह आरंभीकरण चरण के रूप में ट्रिगर किया जा सकता है।
|
||||
|
||||
#### उप-खंड उत्पत्ति (आकांक्षी)
|
||||
|
||||
अधिक बारीक उत्पत्ति के लिए, यह महत्वपूर्ण होगा कि एक त्रिक को एक खंड के भीतर से कहाँ से निकाला गया था, यह सटीक रूप से रिकॉर्ड किया जाए। यह निम्नलिखित को सक्षम करता है:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
यूआई में सटीक स्रोत पाठ को हाइलाइट करना
|
||||
स्रोत के विरुद्ध निष्कर्षण सटीकता को सत्यापित करना
|
||||
वाक्य स्तर पर निष्कर्षण गुणवत्ता को डीबग करना
|
||||
|
||||
**स्थिति ट्रैकिंग के साथ उदाहरण:**
|
||||
```
|
||||
# The extracted triple
|
||||
entity:JohnSmith rel:worksAt entity:AcmeCorp .
|
||||
|
||||
# Subgraph with sub-chunk provenance
|
||||
subgraph:001 tg:contains <<entity:JohnSmith rel:worksAt entity:AcmeCorp>> .
|
||||
subgraph:001 prov:wasDerivedFrom chunk:123-1-1 .
|
||||
subgraph:001 tg:sourceText "John Smith has worked at Acme Corp since 2019" .
|
||||
subgraph:001 tg:sourceCharOffset 1547 .
|
||||
subgraph:001 tg:sourceCharLength 46 .
|
||||
```
|
||||
|
||||
**उदाहरण पाठ सीमा के साथ (वैकल्पिक):**
|
||||
```
|
||||
subgraph:001 tg:contains <<entity:JohnSmith rel:worksAt entity:AcmeCorp>> .
|
||||
subgraph:001 prov:wasDerivedFrom chunk:123-1-1 .
|
||||
subgraph:001 tg:sourceRange "1547-1593" .
|
||||
subgraph:001 tg:sourceText "John Smith has worked at Acme Corp since 2019" .
|
||||
```
|
||||
|
||||
**कार्यान्वयन संबंधी विचार:**
|
||||
|
||||
एलएलएम-आधारित निष्कर्षण स्वाभाविक रूप से वर्ण स्थिति प्रदान नहीं कर सकता है।
|
||||
एलएलएम को निकाले गए त्रिगुटों के साथ स्रोत वाक्य/वाक्यांश वापस करने के लिए प्रेरित किया जा सकता है।
|
||||
वैकल्पिक रूप से, निकाले गए संस्थाओं को स्रोत पाठ से "फजी-मैच" करके पोस्ट-प्रोसेस करें।
|
||||
निष्कर्षण की जटिलता और उत्पत्ति की सूक्ष्मता के बीच एक समझौता।
|
||||
यह संरचित निष्कर्षण विधियों की तुलना में मुफ्त-रूप एलएलएम निष्कर्षण से प्राप्त करना आसान हो सकता है।
|
||||
|
||||
यह एक महत्वाकांक्षी लक्ष्य के रूप में चिह्नित है - मूल रूप से, बुनियादी चंक-स्तरीय उत्पत्ति को पहले लागू किया जाना चाहिए, और यदि संभव हो तो, उप-चंक ट्रैकिंग को भविष्य में एक संवर्द्धन के रूप में लागू किया जा सकता है।
|
||||
|
||||
### दोहरी भंडारण मॉडल
|
||||
|
||||
<<<<<<< HEAD
|
||||
उत्पत्ति डीएजी (DAG) को क्रमिक रूप से बनाया जाता है क्योंकि दस्तावेज़ पाइपलाइन के माध्यम से प्रवाहित होते हैं:
|
||||
=======
|
||||
उत्पत्ति DAG (डायरेक्टेड एसाइक्लिक ग्राफ) को क्रमिक रूप से बनाया जाता है क्योंकि दस्तावेज़ पाइपलाइन के माध्यम से प्रवाहित होते हैं:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
| स्टोर | क्या संग्रहीत है | उद्देश्य |
|
||||
|-------|---------------|---------|
|
||||
| लाइब्रेरियन | दस्तावेज़ सामग्री + माता-पिता-बच्चे लिंक | सामग्री पुनर्प्राप्ति, कैस्केड विलोपन |
|
||||
<<<<<<< HEAD
|
||||
| ज्ञान ग्राफ | माता-पिता-बच्चे किनारे + मेटाडेटा | उत्पत्ति प्रश्न, तथ्य का श्रेय |
|
||||
|
||||
दोनों स्टोर समान डीएजी संरचना बनाए रखते हैं। लाइब्रेरियन सामग्री रखता है; ग्राफ संबंधों को रखता है और ट्रैवर्सल प्रश्नों को सक्षम करता है।
|
||||
|
||||
### प्रमुख डिज़ाइन सिद्धांत
|
||||
|
||||
1. **दस्तावेज़ आईडी प्रवाह की इकाई के रूप में** - प्रोसेसर आईडी, सामग्री नहीं, पास करते हैं। जब आवश्यक हो तो सामग्री लाइब्रेरियन से प्राप्त की जाती है।
|
||||
=======
|
||||
| नॉलेज ग्राफ | माता-पिता-बच्चे किनारे + मेटाडेटा | उत्पत्ति प्रश्न, तथ्य का श्रेय |
|
||||
|
||||
दोनों स्टोर समान DAG संरचना बनाए रखते हैं। लाइब्रेरियन सामग्री रखता है; ग्राफ संबंधों को रखता है और ट्रैवर्सल प्रश्नों को सक्षम बनाता है।
|
||||
|
||||
### प्रमुख डिज़ाइन सिद्धांत
|
||||
|
||||
1. **दस्तावेज़ आईडी प्रवाह की इकाई के रूप में** - प्रोसेसर आईडी, सामग्री नहीं, पास करते हैं। जब आवश्यक हो तो सामग्री को लाइब्रेरियन से प्राप्त किया जाता है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
2. **स्रोत पर एक बार उत्सर्जित करें** - प्रसंस्करण शुरू होने पर मेटाडेटा को ग्राफ में एक बार लिखा जाता है, न कि बाद में दोहराया जाता है।
|
||||
|
||||
3. **संगत प्रोसेसर पैटर्न** - प्रत्येक प्रोसेसर एक ही प्राप्त/प्राप्त/उत्पादित/सहेजें/उत्सर्जित/फॉरवर्ड पैटर्न का पालन करता है।
|
||||
|
||||
<<<<<<< HEAD
|
||||
4. **प्रगतिशील डीएजी निर्माण** - प्रत्येक प्रोसेसर अपने स्तर को डीएजी में जोड़ता है। पूर्ण उत्पत्ति श्रृंखला क्रमिक रूप से बनाई जाती है।
|
||||
|
||||
5. **चंक-प्रोसेसर के बाद अनुकूलन** - चंकिंग के बाद, संदेशों में आईडी और सामग्री दोनों होते हैं। चंक छोटे होते हैं (2-4KB), इसलिए सामग्री को शामिल करने से अनावश्यक लाइब्रेरियन राउंड-ट्रिप से बचा जा सकता है, जबकि आईडी के माध्यम से उत्पत्ति को संरक्षित किया जा सकता है।
|
||||
=======
|
||||
4. **प्रगतिशील DAG निर्माण** - प्रत्येक प्रोसेसर अपने स्तर को DAG में जोड़ता है। पूर्ण उत्पत्ति श्रृंखला क्रमिक रूप से बनाई जाती है।
|
||||
|
||||
5. **चंक-प्रोसेसर के बाद अनुकूलन** - चंकिंग के बाद, संदेशों में आईडी और सामग्री दोनों होते हैं। चंक छोटे होते हैं (2-4KB), इसलिए सामग्री को शामिल करने से अनावश्यक लाइब्रेरियन राउंड-ट्रिप से बचा जाता है, जबकि आईडी के माध्यम से उत्पत्ति को संरक्षित किया जाता है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## कार्यान्वयन कार्य
|
||||
|
||||
### लाइब्रेरियन परिवर्तन
|
||||
|
||||
#### वर्तमान स्थिति
|
||||
|
||||
दस्तावेज़ प्रसंस्करण शुरू करता है दस्तावेज़ आईडी को पहले प्रोसेसर को भेजकर।
|
||||
ट्रिपल स्टोर से कोई कनेक्शन नहीं - मेटाडेटा निष्कर्षण आउटपुट के साथ बंडल किया गया है।
|
||||
`add-child-document` एक-स्तरीय माता-पिता-बच्चे लिंक बनाता है।
|
||||
`list-children` केवल तत्काल बच्चों को वापस करता है।
|
||||
|
||||
#### आवश्यक परिवर्तन
|
||||
|
||||
**1. नया इंटरफ़ेस: ट्रिपल स्टोर कनेक्शन**
|
||||
|
||||
<<<<<<< HEAD
|
||||
लाइब्रेरियन को प्रसंस्करण शुरू करते समय दस्तावेज़ मेटाडेटा किनारों को सीधे ज्ञान ग्राफ में उत्सर्जित करने की आवश्यकता है।
|
||||
=======
|
||||
लाइब्रेरियन को प्रसंस्करण शुरू करते समय दस्तावेज़ मेटाडेटा किनारों को सीधे नॉलेज ग्राफ में उत्सर्जित करने की आवश्यकता है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
लाइब्रेरियन सेवा में ट्रिपल स्टोर क्लाइंट/प्रकाशक जोड़ें।
|
||||
प्रसंस्करण शुरू होने पर: रूट दस्तावेज़ मेटाडेटा को ग्राफ किनारों के रूप में उत्सर्जित करें (एक बार)।
|
||||
|
||||
**2. दस्तावेज़ प्रकार शब्दावली**
|
||||
|
||||
चाइल्ड दस्तावेज़ों के लिए `document_type` मानों का मानकीकरण करें:
|
||||
`source` - मूल अपलोड किया गया दस्तावेज़।
|
||||
<<<<<<< HEAD
|
||||
`page` - स्रोत से निकाला गया पृष्ठ (पीडीएफ, आदि)।
|
||||
=======
|
||||
`page` - स्रोत (पीडीएफ, आदि) से निकाला गया पृष्ठ।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
`chunk` - पृष्ठ या स्रोत से प्राप्त पाठ चंक।
|
||||
|
||||
#### इंटरफ़ेस परिवर्तन सारांश
|
||||
|
||||
| इंटरफ़ेस | परिवर्तन |
|
||||
|-----------|--------|
|
||||
| ट्रिपल स्टोर | नया आउटबाउंड कनेक्शन - दस्तावेज़ मेटाडेटा किनारों को उत्सर्जित करें |
|
||||
| प्रसंस्करण प्रारंभ | ग्राफ पर मेटाडेटा उत्सर्जित करें प्रसंस्करण को अग्रेषित करने से पहले |
|
||||
|
||||
### पीडीएफ एक्सट्रैक्टर परिवर्तन
|
||||
|
||||
#### वर्तमान स्थिति
|
||||
|
||||
दस्तावेज़ सामग्री प्राप्त करता है (या बड़े दस्तावेज़ों को स्ट्रीम करता है)।
|
||||
पीडीएफ पृष्ठों से पाठ निकालता है।
|
||||
पृष्ठ सामग्री को चंकर को अग्रेषित करता है।
|
||||
लाइब्रेरियन या ट्रिपल स्टोर के साथ कोई इंटरैक्शन नहीं।
|
||||
|
||||
#### आवश्यक परिवर्तन
|
||||
|
||||
**1. नया इंटरफ़ेस: लाइब्रेरियन क्लाइंट**
|
||||
|
||||
<<<<<<< HEAD
|
||||
पीडीएफ एक्सट्रैक्टर को प्रत्येक पृष्ठ को लाइब्रेरियन में एक चाइल्ड दस्तावेज़ के रूप में सहेजना होगा।
|
||||
=======
|
||||
पीडीएफ एक्सट्रैक्टर को प्रत्येक पृष्ठ को लाइब्रेरियन में एक चाइल्ड दस्तावेज़ के रूप में सहेजने की आवश्यकता है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
पीडीएफ एक्सट्रैक्टर सेवा में लाइब्रेरियन क्लाइंट जोड़ें।
|
||||
प्रत्येक पृष्ठ के लिए: `add-child-document` को रूट दस्तावेज़ आईडी के साथ कॉल करें।
|
||||
|
||||
**2. नया इंटरफ़ेस: ट्रिपल स्टोर कनेक्शन**
|
||||
|
||||
<<<<<<< HEAD
|
||||
पीडीएफ एक्सट्रैक्टर को ज्ञान ग्राफ में माता-पिता-बच्चे किनारे उत्सर्जित करने की आवश्यकता है।
|
||||
=======
|
||||
पीडीएफ एक्सट्रैक्टर को नॉलेज ग्राफ में माता-पिता-बच्चे किनारों को उत्सर्जित करने की आवश्यकता है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
ट्रिपल स्टोर क्लाइंट/प्रकाशक जोड़ें।
|
||||
प्रत्येक पृष्ठ के लिए: पृष्ठ दस्तावेज़ को माता-पिता दस्तावेज़ से जोड़ने वाले किनारे को उत्सर्जित करें।
|
||||
|
||||
**3. आउटपुट प्रारूप बदलें**
|
||||
|
||||
सीधे पृष्ठ सामग्री अग्रेषित करने के बजाय, पृष्ठ दस्तावेज़ आईडी अग्रेषित करें।
|
||||
<<<<<<< HEAD
|
||||
चंकर लाइब्रेरियन का उपयोग करके आईडी के साथ सामग्री प्राप्त करेगा
|
||||
=======
|
||||
चंकर लाइब्रेरियन का उपयोग करके आईडी के साथ सामग्री प्राप्त करेगा।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
#### इंटरफ़ेस परिवर्तनों का सारांश
|
||||
|
||||
| इंटरफ़ेस | परिवर्तन |
|
||||
|-----------|--------|
|
||||
| लाइब्रेरियन | नया आउटबाउंड - चाइल्ड दस्तावेज़ सहेजें |
|
||||
| ट्रिपल स्टोर | नया आउटबाउंड - पैरेंट-चाइल्ड किनारे उत्सर्जित करें |
|
||||
| आउटपुट संदेश | सामग्री से दस्तावेज़ आईडी में परिवर्तन |
|
||||
|
||||
### चंकर परिवर्तन
|
||||
|
||||
#### वर्तमान स्थिति
|
||||
|
||||
पृष्ठ/पाठ सामग्री प्राप्त करता है
|
||||
टुकड़ों में विभाजित करता है
|
||||
डाउनस्ट्रीम प्रोसेसर को टुकड़े सामग्री अग्रेषित करता है
|
||||
लाइब्रेरियन या ट्रिपल स्टोर के साथ कोई इंटरैक्शन नहीं
|
||||
|
||||
#### आवश्यक परिवर्तन
|
||||
|
||||
**1. इनपुट हैंडलिंग बदलें**
|
||||
|
||||
सामग्री के बजाय दस्तावेज़ आईडी प्राप्त करें, लाइब्रेरियन से प्राप्त करें।
|
||||
चंकर सेवा में लाइब्रेरियन क्लाइंट जोड़ें
|
||||
दस्तावेज़ आईडी का उपयोग करके पृष्ठ सामग्री प्राप्त करें
|
||||
|
||||
**2. नया इंटरफ़ेस: लाइब्रेरियन क्लाइंट (लिखना)**
|
||||
|
||||
प्रत्येक टुकड़े को लाइब्रेरियन में एक चाइल्ड दस्तावेज़ के रूप में सहेजें।
|
||||
प्रत्येक टुकड़े के लिए: `add-child-document` को पैरेंट = पृष्ठ दस्तावेज़ आईडी के साथ कॉल करें
|
||||
|
||||
**3. नया इंटरफ़ेस: ट्रिपल स्टोर कनेक्शन**
|
||||
|
||||
नॉलेज ग्राफ में पैरेंट-चाइल्ड किनारे उत्सर्जित करें।
|
||||
ट्रिपल स्टोर क्लाइंट/प्रकाशक जोड़ें
|
||||
प्रत्येक टुकड़े के लिए: टुकड़े दस्तावेज़ को पृष्ठ दस्तावेज़ से जोड़ने वाला किनारा उत्सर्जित करें
|
||||
|
||||
**4. आउटपुट प्रारूप बदलें**
|
||||
|
||||
टुकड़े दस्तावेज़ आईडी और टुकड़े सामग्री दोनों अग्रेषित करें (टुकड़े-टुकड़े अनुकूलन के बाद)।
|
||||
डाउनस्ट्रीम प्रोसेसर उत्पत्ति के लिए आईडी और काम करने के लिए सामग्री प्राप्त करते हैं
|
||||
|
||||
#### इंटरफ़ेस परिवर्तनों का सारांश
|
||||
|
||||
| इंटरफ़ेस | परिवर्तन |
|
||||
|-----------|--------|
|
||||
| इनपुट संदेश | सामग्री से दस्तावेज़ आईडी में परिवर्तन |
|
||||
| लाइब्रेरियन | नया आउटबाउंड (पढ़ना + लिखना) - सामग्री प्राप्त करें, चाइल्ड दस्तावेज़ सहेजें |
|
||||
| ट्रिपल स्टोर | नया आउटबाउंड - पैरेंट-चाइल्ड किनारे उत्सर्जित करें |
|
||||
| आउटपुट संदेश | सामग्री-केवल से आईडी + सामग्री में परिवर्तन |
|
||||
|
||||
### नॉलेज एक्सट्रैक्टर परिवर्तन
|
||||
|
||||
#### वर्तमान स्थिति
|
||||
|
||||
टुकड़े सामग्री प्राप्त करता है
|
||||
ट्रिपल और एम्बेडिंग निकालता है
|
||||
ट्रिपल स्टोर और एम्बेडिंग स्टोर में उत्सर्जित करता है
|
||||
`subjectOf` संबंध शीर्ष-स्तरीय दस्तावेज़ (टुकड़े नहीं) की ओर इशारा करता है
|
||||
|
||||
#### आवश्यक परिवर्तन
|
||||
|
||||
**1. इनपुट हैंडलिंग बदलें**
|
||||
|
||||
<<<<<<< HEAD
|
||||
टुकड़े दस्तावेज़ आईडी के साथ-साथ सामग्री प्राप्त करें।
|
||||
=======
|
||||
सामग्री के साथ-साथ टुकड़े दस्तावेज़ आईडी प्राप्त करें।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
उत्पत्ति लिंकिंग के लिए टुकड़े आईडी का उपयोग करें (सामग्री पहले से ही अनुकूलन के अनुसार शामिल है)
|
||||
|
||||
**2. ट्रिपल उत्पत्ति को अपडेट करें**
|
||||
|
||||
निकाले गए ट्रिपल को टुकड़े (शीर्ष-स्तरीय दस्तावेज़ नहीं) से लिंक करें।
|
||||
किनारे को इंगित करने वाले किनारे को बनाने के लिए पुन: उपयोग करें
|
||||
`subjectOf` संबंध: ट्रिपल → टुकड़े दस्तावेज़ आईडी
|
||||
मौजूदा पुन: उपयोग समर्थन का पहला उपयोग
|
||||
|
||||
**3. एम्बेडिंग उत्पत्ति को अपडेट करें**
|
||||
|
||||
<<<<<<< HEAD
|
||||
एम्बेडिंग इकाई आईडी को टुकड़े से लिंक करें।
|
||||
किनारा उत्सर्जित करें: एम्बेडिंग इकाई आईडी → टुकड़े दस्तावेज़ आईडी
|
||||
=======
|
||||
एम्बेडिंग एंटिटी आईडी को टुकड़े से लिंक करें।
|
||||
किनारा उत्सर्जित करें: एम्बेडिंग एंटिटी आईडी → टुकड़े दस्तावेज़ आईडी
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
#### इंटरफ़ेस परिवर्तनों का सारांश
|
||||
|
||||
| इंटरफ़ेस | परिवर्तन |
|
||||
|-----------|--------|
|
||||
<<<<<<< HEAD
|
||||
| इनपुट संदेश | टुकड़े आईडी + सामग्री की अपेक्षा करें (केवल सामग्री नहीं) |
|
||||
| ट्रिपल स्टोर | ट्रिपल → टुकड़े उत्पत्ति के लिए पुन: उपयोग का उपयोग करें |
|
||||
| एम्बेडिंग उत्पत्ति | इकाई आईडी → टुकड़े आईडी से लिंक करें |
|
||||
=======
|
||||
| इनपुट संदेश | सामग्री के साथ टुकड़े आईडी + सामग्री की अपेक्षा करें (केवल सामग्री नहीं) |
|
||||
| ट्रिपल स्टोर | ट्रिपल → टुकड़े उत्पत्ति के लिए पुन: उपयोग का उपयोग करें |
|
||||
| एम्बेडिंग उत्पत्ति | एंटिटी आईडी → टुकड़े आईडी से लिंक करें |
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## संदर्भ
|
||||
|
||||
क्वेरी-टाइम उत्पत्ति: `docs/tech-specs/query-time-provenance.md`
|
||||
उत्पत्ति मॉडलिंग के लिए PROV-O मानक
|
||||
नॉलेज ग्राफ में मौजूदा स्रोत मेटाडेटा (ऑडिट की आवश्यकता है)
|
||||
328
docs/tech-specs/hi/flow-class-definition.hi.md
Normal file
328
docs/tech-specs/hi/flow-class-definition.hi.md
Normal file
|
|
@ -0,0 +1,328 @@
|
|||
---
|
||||
layout: default
|
||||
title: "फ्लो ब्लूप्रिंट परिभाषा विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# फ्लो ब्लूप्रिंट परिभाषा विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
एक फ्लो ब्लूप्रिंट ट्रस्टग्राफ सिस्टम में एक पूर्ण डेटाफ्लो पैटर्न टेम्पलेट को परिभाषित करता है। जब इसे कार्यान्वित किया जाता है, तो यह प्रोसेसर का एक अंतर्संबंधित नेटवर्क बनाता है जो डेटा इनपुट, प्रसंस्करण, भंडारण और क्वेरी को एक एकीकृत प्रणाली के रूप में संभालता है।
|
||||
|
||||
## संरचना
|
||||
|
||||
एक फ्लो ब्लूप्रिंट परिभाषा में पाँच मुख्य अनुभाग होते हैं:
|
||||
|
||||
### 1. क्लास अनुभाग
|
||||
<<<<<<< HEAD
|
||||
यह साझा सेवा प्रोसेसर को परिभाषित करता है जिन्हें प्रत्येक फ्लो ब्लूप्रिंट के लिए एक बार इंस्टेंट किया जाता है। ये प्रोसेसर इस क्लास के सभी फ्लो उदाहरणों से अनुरोधों को संभालते हैं।
|
||||
=======
|
||||
साझा सेवा प्रोसेसर को परिभाषित करता है जिन्हें प्रत्येक फ्लो ब्लूप्रिंट के लिए एक बार इंस्टेंट किया जाता है। ये प्रोसेसर इस क्लास के सभी फ्लो उदाहरणों से अनुरोधों को संभालते हैं।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
```json
|
||||
"class": {
|
||||
"service-name:{class}": {
|
||||
"request": "queue-pattern:{class}",
|
||||
"response": "queue-pattern:{class}",
|
||||
"settings": {
|
||||
"setting-name": "fixed-value",
|
||||
"parameterized-setting": "{parameter-name}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**विशेषताएं:**
|
||||
समान वर्ग के सभी फ्लो उदाहरणों में साझा किया जाता है।
|
||||
आमतौर पर महंगी या स्टेटलेस सेवाएं (एलएलएम, एम्बेडिंग मॉडल)।
|
||||
<<<<<<< HEAD
|
||||
कतार नामकरण के लिए `{class}` टेम्पलेट वेरिएबल का उपयोग करें।
|
||||
=======
|
||||
क्यू नामकरण के लिए `{class}` टेम्पलेट वेरिएबल का उपयोग करें।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
सेटिंग्स निश्चित मान हो सकती हैं या `{parameter-name}` सिंटैक्स के साथ पैरामीटराइज़ की जा सकती हैं।
|
||||
उदाहरण: `embeddings:{class}`, `text-completion:{class}`, `graph-rag:{class}`
|
||||
|
||||
### 2. फ्लो सेक्शन
|
||||
फ्लो-विशिष्ट प्रोसेसर को परिभाषित करता है जिन्हें प्रत्येक व्यक्तिगत फ्लो उदाहरण के लिए इंस्टेंट किया जाता है। प्रत्येक फ्लो को इन प्रोसेसर का अपना अलग सेट मिलता है।
|
||||
|
||||
```json
|
||||
"flow": {
|
||||
"processor-name:{id}": {
|
||||
"input": "queue-pattern:{id}",
|
||||
"output": "queue-pattern:{id}",
|
||||
"settings": {
|
||||
"setting-name": "fixed-value",
|
||||
"parameterized-setting": "{parameter-name}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**विशेषताएं:**
|
||||
प्रत्येक प्रवाह के लिए अद्वितीय उदाहरण।
|
||||
प्रवाह-विशिष्ट डेटा और स्थिति को संभालें।
|
||||
कतार नामकरण के लिए `{id}` टेम्पलेट चर का उपयोग करें।
|
||||
सेटिंग्स या तो निश्चित मान हो सकती हैं या `{parameter-name}` सिंटैक्स के साथ पैरामीटराइज़ की जा सकती हैं।
|
||||
उदाहरण: `chunker:{id}`, `pdf-decoder:{id}`, `kg-extract-relationships:{id}`
|
||||
|
||||
### 3. इंटरफेस अनुभाग
|
||||
<<<<<<< HEAD
|
||||
यह प्रवाह के लिए प्रवेश बिंदुओं और इंटरैक्शन अनुबंधों को परिभाषित करता है। ये बाहरी प्रणालियों और आंतरिक घटक संचार के लिए एपीआई सतह बनाते हैं।
|
||||
=======
|
||||
यह प्रवाह के लिए प्रवेश बिंदु और इंटरैक्शन अनुबंधों को परिभाषित करता है। ये बाहरी प्रणालियों और आंतरिक घटक संचार के लिए एपीआई सतह बनाते हैं।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
इंटरफेस दो रूप ले सकते हैं:
|
||||
|
||||
**फायर-एंड-फॉरगेट पैटर्न** (एक कतार):
|
||||
```json
|
||||
"interfaces": {
|
||||
"document-load": "persistent://tg/flow/document-load:{id}",
|
||||
"triples-store": "persistent://tg/flow/triples-store:{id}"
|
||||
}
|
||||
```
|
||||
|
||||
**अनुरोध/प्रतिक्रिया पैटर्न** (अनुरोध/प्रतिक्रिया फ़ील्ड वाले ऑब्जेक्ट):
|
||||
```json
|
||||
"interfaces": {
|
||||
"embeddings": {
|
||||
"request": "non-persistent://tg/request/embeddings:{class}",
|
||||
"response": "non-persistent://tg/response/embeddings:{class}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**इंटरफेस के प्रकार:**
|
||||
**एंट्री पॉइंट:** वे स्थान जहाँ बाहरी सिस्टम डेटा इंजेक्ट करते हैं (`document-load`, `agent`)
|
||||
**सर्विस इंटरफेस:** सेवाओं के लिए अनुरोध/प्रतिक्रिया पैटर्न (`embeddings`, `text-completion`)
|
||||
**डेटा इंटरफेस:** फायर-एंड-फॉरगेट डेटा प्रवाह कनेक्शन बिंदु (`triples-store`, `entity-contexts-load`)
|
||||
|
||||
### 4. पैरामीटर अनुभाग
|
||||
यह प्रवाह-विशिष्ट पैरामीटर नामों को केंद्रीय रूप से संग्रहीत पैरामीटर परिभाषाओं से जोड़ता है:
|
||||
|
||||
```json
|
||||
"parameters": {
|
||||
"model": "llm-model",
|
||||
"temp": "temperature",
|
||||
"chunk": "chunk-size"
|
||||
}
|
||||
```
|
||||
|
||||
**विशेषताएं:**
|
||||
कुंजियाँ प्रोसेसर सेटिंग्स में उपयोग किए जाने वाले पैरामीटर नामों को संदर्भित करती हैं (उदाहरण के लिए, `{model}`)
|
||||
मान स्कीमा/कॉन्फ़िगरेशन में संग्रहीत पैरामीटर परिभाषाओं को संदर्भित करते हैं।
|
||||
यह सामान्य पैरामीटर परिभाषाओं को विभिन्न फ्लो में पुन: उपयोग करने की अनुमति देता है।
|
||||
पैरामीटर स्कीमा की डुप्लिकेसी को कम करता है।
|
||||
|
||||
### 5. मेटाडेटा
|
||||
फ्लो ब्लूप्रिंट के बारे में अतिरिक्त जानकारी:
|
||||
|
||||
```json
|
||||
"description": "Human-readable description",
|
||||
"tags": ["capability-1", "capability-2"]
|
||||
```
|
||||
|
||||
## टेम्पलेट वेरिएबल
|
||||
|
||||
### सिस्टम वेरिएबल
|
||||
|
||||
#### {id}
|
||||
यह अद्वितीय फ्लो इंस्टेंस पहचानकर्ता से प्रतिस्थापित किया जाता है।
|
||||
यह प्रत्येक फ्लो के लिए अलग-अलग संसाधन बनाता है।
|
||||
उदाहरण: `flow-123`, `customer-A-flow`
|
||||
|
||||
#### {class}
|
||||
यह फ्लो ब्लूप्रिंट नाम से प्रतिस्थापित किया जाता है।
|
||||
यह समान क्लास के फ्लो में साझा संसाधनों का निर्माण करता है।
|
||||
उदाहरण: `standard-rag`, `enterprise-rag`
|
||||
|
||||
### पैरामीटर वेरिएबल
|
||||
|
||||
#### {पैरामीटर-नाम}
|
||||
फ्लो लॉन्च करते समय परिभाषित कस्टम पैरामीटर।
|
||||
पैरामीटर नाम फ्लो के `parameters` अनुभाग में कुंजियों से मेल खाते हैं।
|
||||
प्रोसेसर सेटिंग्स में व्यवहार को अनुकूलित करने के लिए उपयोग किया जाता है।
|
||||
उदाहरण: `{model}`, `{temp}`, `{chunk}`
|
||||
फ्लो लॉन्च करते समय प्रदान किए गए मानों से प्रतिस्थापित किया जाता है।
|
||||
केंद्रीय रूप से संग्रहीत पैरामीटर परिभाषाओं के विरुद्ध मान्य किया जाता है।
|
||||
|
||||
## प्रोसेसर सेटिंग्स
|
||||
|
||||
सेटिंग्स, इंस्टैंशिएशन के समय प्रोसेसरों को कॉन्फ़िगरेशन मान प्रदान करती हैं। वे निम्न हो सकते हैं:
|
||||
|
||||
### फिक्स्ड सेटिंग्स
|
||||
सीधे मान जो नहीं बदलते:
|
||||
```json
|
||||
"settings": {
|
||||
"model": "gemma3:12b",
|
||||
"temperature": 0.7,
|
||||
"max_retries": 3
|
||||
}
|
||||
```
|
||||
|
||||
### पैरामीटराइज़्ड सेटिंग्स
|
||||
<<<<<<< HEAD
|
||||
वे मान जो प्रवाह शुरू करते समय प्रदान किए गए पैरामीटर का उपयोग करते हैं:
|
||||
=======
|
||||
वे मान जो फ्लो शुरू करते समय प्रदान किए गए पैरामीटर का उपयोग करते हैं:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
```json
|
||||
"settings": {
|
||||
"model": "{model}",
|
||||
"temperature": "{temp}",
|
||||
"endpoint": "https://{region}.api.example.com"
|
||||
}
|
||||
```
|
||||
|
||||
सेटिंग्स में पैरामीटर नाम, प्रवाह के `parameters` अनुभाग में कुंजियों से मेल खाते हैं।
|
||||
|
||||
### सेटिंग्स के उदाहरण
|
||||
|
||||
**पैरामीटर के साथ एलएलएम प्रोसेसर:**
|
||||
```json
|
||||
// In parameters section:
|
||||
"parameters": {
|
||||
"model": "llm-model",
|
||||
"temp": "temperature",
|
||||
"tokens": "max-tokens",
|
||||
"key": "openai-api-key"
|
||||
}
|
||||
|
||||
// In processor definition:
|
||||
"text-completion:{class}": {
|
||||
"request": "non-persistent://tg/request/text-completion:{class}",
|
||||
"response": "non-persistent://tg/response/text-completion:{class}",
|
||||
"settings": {
|
||||
"model": "{model}",
|
||||
"temperature": "{temp}",
|
||||
"max_tokens": "{tokens}",
|
||||
"api_key": "{key}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**निश्चित और पैरामीटराइज़्ड सेटिंग्स के साथ चंकर:**
|
||||
```json
|
||||
// In parameters section:
|
||||
"parameters": {
|
||||
"chunk": "chunk-size"
|
||||
}
|
||||
|
||||
// In processor definition:
|
||||
"chunker:{id}": {
|
||||
"input": "persistent://tg/flow/chunk:{id}",
|
||||
"output": "persistent://tg/flow/chunk-load:{id}",
|
||||
"settings": {
|
||||
"chunk_size": "{chunk}",
|
||||
"chunk_overlap": 100,
|
||||
"encoding": "utf-8"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## क्यू पैटर्न (पल्सर)
|
||||
|
||||
फ्लो ब्लूप्रिंट्स संदेश भेजने के लिए अपाचे पल्सर का उपयोग करते हैं। क्यू नामों का प्रारूप पल्सर प्रारूप का अनुसरण करता है:
|
||||
```
|
||||
<persistence>://<tenant>/<namespace>/<topic>
|
||||
```
|
||||
|
||||
### घटक:
|
||||
**स्थायित्व**: `persistent` या `non-persistent` (पल्सर स्थायित्व मोड)
|
||||
<<<<<<< HEAD
|
||||
**किरायेदार**: ट्रस्टग्राफ द्वारा प्रदान किए गए प्रवाह ब्लूप्रिंट परिभाषाओं के लिए `tg`
|
||||
=======
|
||||
**किरायेदार**: ट्रस्टग्राफ द्वारा प्रदान किए गए फ़्लो ब्लूप्रिंट परिभाषाओं के लिए `tg`
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**नामस्थान**: यह संदेश पैटर्न को इंगित करता है
|
||||
`flow`: फायर-एंड-फॉरगेट सेवाएं
|
||||
`request`: अनुरोध/प्रतिक्रिया सेवाओं का अनुरोध भाग
|
||||
`response`: अनुरोध/प्रतिक्रिया सेवाओं का प्रतिक्रिया भाग
|
||||
**विषय**: टेम्पलेट चर के साथ विशिष्ट कतार/विषय नाम
|
||||
|
||||
### स्थायी कतारें
|
||||
पैटर्न: `persistent://tg/flow/<topic>:{id}`
|
||||
फायर-एंड-फॉरगेट सेवाओं और टिकाऊ डेटा प्रवाह के लिए उपयोग किया जाता है
|
||||
डेटा पल्सर स्टोरेज में पुनरारंभों में बना रहता है
|
||||
उदाहरण: `persistent://tg/flow/chunk-load:{id}`
|
||||
|
||||
### गैर-स्थायी कतारें
|
||||
पैटर्न: `non-persistent://tg/request/<topic>:{class}` या `non-persistent://tg/response/<topic>:{class}`
|
||||
अनुरोध/प्रतिक्रिया संदेश पैटर्न के लिए उपयोग किया जाता है
|
||||
अस्थिर, पल्सर द्वारा डिस्क पर संग्रहीत नहीं है
|
||||
कम विलंबता, RPC-शैली संचार के लिए उपयुक्त
|
||||
उदाहरण: `non-persistent://tg/request/embeddings:{class}`
|
||||
|
||||
## डेटाफ्लो आर्किटेक्चर
|
||||
|
||||
<<<<<<< HEAD
|
||||
प्रवाह ब्लूप्रिंट एक एकीकृत डेटाफ्लो बनाता है जहां:
|
||||
=======
|
||||
फ़्लो ब्लूप्रिंट एक एकीकृत डेटाफ्लो बनाता है जहां:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
1. **दस्तावेज़ प्रसंस्करण पाइपलाइन**: अंतर्ग्रहण से लेकर परिवर्तन और भंडारण तक का प्रवाह
|
||||
2. **क्वेरी सेवाएं**: एकीकृत प्रोसेसर जो समान डेटा स्टोर और सेवाओं को क्वेरी करते हैं
|
||||
3. **साझा सेवाएं**: केंद्रीय प्रोसेसर जिनका उपयोग सभी प्रवाह कर सकते हैं
|
||||
<<<<<<< HEAD
|
||||
4. **भंडारण लेखक**: संसाधित डेटा को उपयुक्त स्टोर में सहेजें
|
||||
|
||||
सभी प्रोसेसर (दोनों `{id}` और `{class}`) एक सुसंगत डेटाफ्लो ग्राफ के रूप में एक साथ काम करते हैं, अलग-अलग सिस्टम के रूप में नहीं।
|
||||
|
||||
## उदाहरण प्रवाह कार्यान्वयन
|
||||
|
||||
दिया गया:
|
||||
प्रवाह उदाहरण आईडी: `customer-A-flow`
|
||||
प्रवाह ब्लूप्रिंट: `standard-rag`
|
||||
प्रवाह पैरामीटर मैपिंग:
|
||||
=======
|
||||
4. **भंडारण लेखक**: संसाधित डेटा को उपयुक्त स्टोर में संग्रहीत करते हैं
|
||||
|
||||
सभी प्रोसेसर (दोनों `{id}` और `{class}`) एक सुसंगत डेटाफ्लो ग्राफ के रूप में एक साथ काम करते हैं, अलग-अलग सिस्टम के रूप में नहीं।
|
||||
|
||||
## उदाहरण फ़्लो इंस्टेंशिएशन
|
||||
|
||||
दिया गया:
|
||||
फ़्लो इंस्टेंस आईडी: `customer-A-flow`
|
||||
फ़्लो ब्लूप्रिंट: `standard-rag`
|
||||
फ़्लो पैरामीटर मैपिंग:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
`"model": "llm-model"`
|
||||
`"temp": "temperature"`
|
||||
`"chunk": "chunk-size"`
|
||||
उपयोगकर्ता-प्रदत्त पैरामीटर:
|
||||
`model`: `gpt-4`
|
||||
`temp`: `0.5`
|
||||
`chunk`: `512`
|
||||
|
||||
टेम्पलेट विस्तार:
|
||||
`persistent://tg/flow/chunk-load:{id}` → `persistent://tg/flow/chunk-load:customer-A-flow`
|
||||
`non-persistent://tg/request/embeddings:{class}` → `non-persistent://tg/request/embeddings:standard-rag`
|
||||
`"model": "{model}"` → `"model": "gpt-4"`
|
||||
`"temperature": "{temp}"` → `"temperature": "0.5"`
|
||||
`"chunk_size": "{chunk}"` → `"chunk_size": "512"`
|
||||
|
||||
यह बनाता है:
|
||||
`customer-A-flow` के लिए अलग दस्तावेज़ प्रसंस्करण पाइपलाइन
|
||||
सभी `standard-rag` प्रवाह के लिए साझा एम्बेडिंग सेवा
|
||||
दस्तावेज़ अंतर्ग्रहण से लेकर क्वेरी तक का पूर्ण डेटाफ्लो
|
||||
प्रोसेसर प्रदान किए गए पैरामीटर मानों के साथ कॉन्फ़िगर किए गए
|
||||
|
||||
## लाभ
|
||||
|
||||
1. **संसाधन दक्षता**: महंगी सेवाओं को प्रवाह में साझा किया जाता है
|
||||
<<<<<<< HEAD
|
||||
2. **प्रवाह अलगाव**: प्रत्येक प्रवाह का अपना डेटा प्रसंस्करण पाइपलाइन होता है
|
||||
3. **मापनीयता**: एक ही टेम्पलेट से कई प्रवाहों को कार्यान्वित किया जा सकता है
|
||||
4. **मॉड्यूलरिटी**: साझा और प्रवाह-विशिष्ट घटकों के बीच स्पष्ट अलगाव
|
||||
=======
|
||||
2. **फ़्लो अलगाव**: प्रत्येक फ़्लो का अपना डेटा प्रसंस्करण पाइपलाइन होता है
|
||||
3. **मापनीयता**: एक ही टेम्पलेट से कई फ़्लो को इंस्टेंशिएट किया जा सकता है
|
||||
4. **मॉड्यूलरिटी**: साझा और फ़्लो-विशिष्ट घटकों के बीच स्पष्ट अलगाव
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
5. **एकीकृत आर्किटेक्चर**: क्वेरी और प्रसंस्करण एक ही डेटाफ्लो का हिस्सा हैं
|
||||
598
docs/tech-specs/hi/flow-configurable-parameters.hi.md
Normal file
598
docs/tech-specs/hi/flow-configurable-parameters.hi.md
Normal file
|
|
@ -0,0 +1,598 @@
|
|||
---
|
||||
layout: default
|
||||
title: "फ्लो ब्लूप्रिंट कॉन्फ़िगर करने योग्य पैरामीटर तकनीकी विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# फ्लो ब्लूप्रिंट कॉन्फ़िगर करने योग्य पैरामीटर तकनीकी विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह विनिर्देश ट्रस्टग्राफ में कॉन्फ़िगर करने योग्य पैरामीटर के कार्यान्वयन का वर्णन करता है। पैरामीटर उपयोगकर्ताओं को फ्लो लॉन्च समय पर प्रोसेसर पैरामीटर को अनुकूलित करने की अनुमति देते हैं, जो फ्लो ब्लूप्रिंट परिभाषा में पैरामीटर प्लेसहोल्डर को बदलने वाले मान प्रदान करते हैं।
|
||||
|
||||
पैरामीटर प्रोसेसर पैरामीटर में टेम्पलेट वेरिएबल प्रतिस्थापन के माध्यम से काम करते हैं, जो `{id}` और `{class}` वेरिएबल्स के काम करने के तरीके के समान है, लेकिन उपयोगकर्ता-प्रदत्त मानों के साथ।
|
||||
|
||||
एकीकरण चार प्राथमिक उपयोग मामलों का समर्थन करता है:
|
||||
|
||||
1. **मॉडल चयन**: उपयोगकर्ताओं को प्रोसेसर के लिए विभिन्न एलएलएम मॉडल (जैसे, `gemma3:8b`, `gpt-4`, `claude-3`) चुनने की अनुमति देना
|
||||
2. **संसाधन कॉन्फ़िगरेशन**: प्रोसेसर पैरामीटर जैसे कि चंक आकार, बैच आकार और समवर्ती सीमा को समायोजित करना
|
||||
3. **व्यवहार ट्यूनिंग**: तापमान, अधिकतम-टोकन या पुनर्प्राप्ति थ्रेसहोल्ड जैसे पैरामीटर के माध्यम से प्रोसेसर व्यवहार को संशोधित करना
|
||||
<<<<<<< HEAD
|
||||
4. **पर्यावरण-विशिष्ट पैरामीटर**: प्रत्येक परिनियोजन के लिए समापन बिंदु, एपीआई कुंजियाँ या क्षेत्र-विशिष्ट यूआरएल को कॉन्फ़िगर करना
|
||||
=======
|
||||
4. **पर्यावरण-विशिष्ट पैरामीटर**: प्रत्येक तैनाती के लिए समापन बिंदु, एपीआई कुंजियाँ या क्षेत्र-विशिष्ट यूआरएल को कॉन्फ़िगर करना
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
**डायनामिक प्रोसेसर कॉन्फ़िगरेशन**: पैरामीटर प्रतिस्थापन के माध्यम से प्रोसेसर पैरामीटर के रनटाइम कॉन्फ़िगरेशन को सक्षम करना
|
||||
**पैरामीटर सत्यापन**: फ्लो लॉन्च समय पर पैरामीटर के लिए टाइप चेकिंग और सत्यापन प्रदान करना
|
||||
<<<<<<< HEAD
|
||||
**डिफ़ॉल्ट मान**: समझदार डिफ़ॉल्ट का समर्थन करना जबकि उन्नत उपयोगकर्ताओं के लिए ओवरराइड की अनुमति देना
|
||||
=======
|
||||
**डिफ़ॉल्ट मान**: समझदार डिफ़ॉल्ट मानों का समर्थन करना जबकि उन्नत उपयोगकर्ताओं के लिए ओवरराइड की अनुमति देना
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**टेम्पलेट प्रतिस्थापन**: प्रोसेसर पैरामीटर में पैरामीटर प्लेसहोल्डर को निर्बाध रूप से बदलना
|
||||
**यूआई एकीकरण**: एपीआई और यूआई इंटरफेस दोनों के माध्यम से पैरामीटर इनपुट को सक्षम करना
|
||||
**टाइप सुरक्षा**: यह सुनिश्चित करना कि पैरामीटर प्रकार अपेक्षित प्रोसेसर पैरामीटर प्रकारों से मेल खाते हैं
|
||||
**प्रलेखन**: फ्लो ब्लूप्रिंट परिभाषाओं के भीतर स्व-प्रलेखित पैरामीटर स्कीमा
|
||||
<<<<<<< HEAD
|
||||
**पिछड़ा संगतता**: मौजूदा फ्लो ब्लूप्रिंट के साथ संगतता बनाए रखना जो पैरामीटर का उपयोग नहीं करते हैं
|
||||
=======
|
||||
**पिछला संगतता**: मौजूदा फ्लो ब्लूप्रिंट के साथ संगतता बनाए रखना जो पैरामीटर का उपयोग नहीं करते हैं
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## पृष्ठभूमि
|
||||
|
||||
ट्रस्टग्राफ में फ्लो ब्लूप्रिंट अब प्रोसेसर पैरामीटर का समर्थन करते हैं जिनमें या तो निश्चित मान या पैरामीटर प्लेसहोल्डर हो सकते हैं। यह रनटाइम अनुकूलन के लिए एक अवसर बनाता है।
|
||||
|
||||
वर्तमान प्रोसेसर पैरामीटर का समर्थन:
|
||||
निश्चित मान: `"model": "gemma3:12b"`
|
||||
पैरामीटर प्लेसहोल्डर: `"model": "gemma3:{model-size}"`
|
||||
|
||||
यह विनिर्देश परिभाषित करता है कि पैरामीटर कैसे हैं:
|
||||
फ्लो ब्लूप्रिंट परिभाषाओं में घोषित
|
||||
जब फ्लो लॉन्च होते हैं तो मान्य
|
||||
प्रोसेसर पैरामीटर में प्रतिस्थापित
|
||||
एपीआई और यूआई के माध्यम से उजागर
|
||||
|
||||
पैरामीटराइज़्ड प्रोसेसर पैरामीटर का लाभ उठाकर, ट्रस्टग्राफ:
|
||||
भिन्नताओं के लिए पैरामीटर का उपयोग करके फ्लो ब्लूप्रिंट डुप्लिकेसन को कम करता है
|
||||
उपयोगकर्ताओं को परिभाषाओं को संशोधित किए बिना प्रोसेसर व्यवहार को ट्यून करने की अनुमति देता है
|
||||
पैरामीटर मानों के माध्यम से पर्यावरण-विशिष्ट कॉन्फ़िगरेशन का समर्थन करता है
|
||||
पैरामीटर स्कीमा सत्यापन के माध्यम से टाइप सुरक्षा बनाए रखता है
|
||||
|
||||
## तकनीकी डिजाइन
|
||||
|
||||
### वास्तुकला
|
||||
|
||||
कॉन्फ़िगर करने योग्य पैरामीटर सिस्टम के लिए निम्नलिखित तकनीकी घटकों की आवश्यकता होती है:
|
||||
|
||||
1. **पैरामीटर स्कीमा परिभाषा**
|
||||
फ्लो ब्लूप्रिंट मेटाडेटा के भीतर JSON स्कीमा-आधारित पैरामीटर परिभाषाएँ
|
||||
<<<<<<< HEAD
|
||||
स्ट्रिंग, नंबर, बूलियन, एनम और ऑब्जेक्ट प्रकार सहित प्रकार परिभाषाएँ
|
||||
=======
|
||||
स्ट्रिंग, संख्या, बूलियन, एनम और ऑब्जेक्ट प्रकार सहित प्रकार परिभाषाएँ
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
न्यूनतम/अधिकतम मान, पैटर्न और आवश्यक फ़ील्ड सहित सत्यापन नियम
|
||||
|
||||
मॉड्यूल: trustgraph-flow/trustgraph/flow/definition.py
|
||||
|
||||
2. **पैरामीटर रिज़ॉल्यूशन इंजन**
|
||||
स्कीमा के विरुद्ध रनटाइम पैरामीटर सत्यापन
|
||||
निर्दिष्ट पैरामीटर के लिए डिफ़ॉल्ट मानों का अनुप्रयोग
|
||||
फ्लो निष्पादन संदर्भ में पैरामीटर इंजेक्शन
|
||||
आवश्यकतानुसार प्रकार का रूपांतरण और रूपांतरण
|
||||
|
||||
मॉड्यूल: trustgraph-flow/trustgraph/flow/parameter_resolver.py
|
||||
|
||||
3. **पैरामीटर स्टोर एकीकरण**
|
||||
स्कीमा/कॉन्फ़िग स्टोर से पैरामीटर परिभाषाओं की पुनर्प्राप्ति
|
||||
<<<<<<< HEAD
|
||||
अक्सर उपयोग की जाने वाली पैरामीटर परिभाषाओं का कैशिंग
|
||||
=======
|
||||
बार-बार उपयोग की जाने वाली पैरामीटर परिभाषाओं का कैशिंग
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
केंद्रीय रूप से संग्रहीत स्कीमा के विरुद्ध सत्यापन
|
||||
|
||||
मॉड्यूल: trustgraph-flow/trustgraph/flow/parameter_store.py
|
||||
|
||||
4. **फ्लो लॉन्चर एक्सटेंशन**
|
||||
फ्लो लॉन्च के दौरान पैरामीटर मानों को स्वीकार करने के लिए एपीआई एक्सटेंशन
|
||||
पैरामीटर मैपिंग रिज़ॉल्यूशन (फ्लो नाम से परिभाषा नाम)
|
||||
अमान्य पैरामीटर संयोजनों के लिए त्रुटि हैंडलिंग
|
||||
|
||||
मॉड्यूल: trustgraph-flow/trustgraph/flow/launcher.py
|
||||
|
||||
5. **यूआई पैरामीटर फॉर्म**
|
||||
फ्लो पैरामीटर मेटाडेटा से गतिशील रूप से उत्पन्न फॉर्म
|
||||
`order` फ़ील्ड का उपयोग करके क्रमबद्ध पैरामीटर प्रदर्शन
|
||||
`description` फ़ील्ड का उपयोग करके वर्णनात्मक पैरामीटर लेबल
|
||||
पैरामीटर प्रकार परिभाषाओं के विरुद्ध इनपुट सत्यापन
|
||||
पैरामीटर प्रीसेट और टेम्पलेट
|
||||
|
||||
मॉड्यूल: trustgraph-ui/components/flow-parameters/
|
||||
|
||||
### डेटा मॉडल
|
||||
|
||||
#### पैरामीटर परिभाषाएँ (स्कीमा/कॉन्फ़िग में संग्रहीत)
|
||||
|
||||
पैरामीटर परिभाषाएँ स्कीमा और कॉन्फ़िग सिस्टम में "पैरामीटर-प्रकार" प्रकार के साथ केंद्रीय रूप से संग्रहीत की जाती हैं:
|
||||
|
||||
```json
|
||||
{
|
||||
"llm-model": {
|
||||
"type": "string",
|
||||
"description": "LLM model to use",
|
||||
"default": "gpt-4",
|
||||
"enum": [
|
||||
{
|
||||
"id": "gpt-4",
|
||||
"description": "OpenAI GPT-4 (Most Capable)"
|
||||
},
|
||||
{
|
||||
"id": "gpt-3.5-turbo",
|
||||
"description": "OpenAI GPT-3.5 Turbo (Fast & Efficient)"
|
||||
},
|
||||
{
|
||||
"id": "claude-3",
|
||||
"description": "Anthropic Claude 3 (Thoughtful & Safe)"
|
||||
},
|
||||
{
|
||||
"id": "gemma3:8b",
|
||||
"description": "Google Gemma 3 8B (Open Source)"
|
||||
}
|
||||
],
|
||||
"required": false
|
||||
},
|
||||
"model-size": {
|
||||
"type": "string",
|
||||
"description": "Model size variant",
|
||||
"default": "8b",
|
||||
"enum": ["2b", "8b", "12b", "70b"],
|
||||
"required": false
|
||||
},
|
||||
"temperature": {
|
||||
"type": "number",
|
||||
"description": "Model temperature for generation",
|
||||
"default": 0.7,
|
||||
"minimum": 0.0,
|
||||
"maximum": 2.0,
|
||||
"required": false
|
||||
},
|
||||
"chunk-size": {
|
||||
"type": "integer",
|
||||
"description": "Document chunk size",
|
||||
"default": 512,
|
||||
"minimum": 128,
|
||||
"maximum": 2048,
|
||||
"required": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### पैरामीटर संदर्भों के साथ फ्लो ब्लूप्रिंट
|
||||
|
||||
फ्लो ब्लूप्रिंट, प्रकार संदर्भों, विवरणों और क्रम के साथ पैरामीटर मेटाडेटा को परिभाषित करते हैं:
|
||||
|
||||
```json
|
||||
{
|
||||
"flow_class": "document-analysis",
|
||||
"parameters": {
|
||||
"llm-model": {
|
||||
"type": "llm-model",
|
||||
"description": "Primary LLM model for text completion",
|
||||
"order": 1
|
||||
},
|
||||
"llm-rag-model": {
|
||||
"type": "llm-model",
|
||||
"description": "LLM model for RAG operations",
|
||||
"order": 2,
|
||||
"advanced": true,
|
||||
"controlled-by": "llm-model"
|
||||
},
|
||||
"llm-temperature": {
|
||||
"type": "temperature",
|
||||
"description": "Generation temperature for creativity control",
|
||||
"order": 3,
|
||||
"advanced": true
|
||||
},
|
||||
"chunk-size": {
|
||||
"type": "chunk-size",
|
||||
"description": "Document chunk size for processing",
|
||||
"order": 4,
|
||||
"advanced": true
|
||||
},
|
||||
"chunk-overlap": {
|
||||
"type": "integer",
|
||||
"description": "Overlap between document chunks",
|
||||
"order": 5,
|
||||
"advanced": true,
|
||||
"controlled-by": "chunk-size"
|
||||
}
|
||||
},
|
||||
"class": {
|
||||
"text-completion:{class}": {
|
||||
"request": "non-persistent://tg/request/text-completion:{class}",
|
||||
"response": "non-persistent://tg/response/text-completion:{class}",
|
||||
"parameters": {
|
||||
"model": "{llm-model}",
|
||||
"temperature": "{llm-temperature}"
|
||||
}
|
||||
},
|
||||
"rag-completion:{class}": {
|
||||
"request": "non-persistent://tg/request/rag-completion:{class}",
|
||||
"response": "non-persistent://tg/response/rag-completion:{class}",
|
||||
"parameters": {
|
||||
"model": "{llm-rag-model}",
|
||||
"temperature": "{llm-temperature}"
|
||||
}
|
||||
}
|
||||
},
|
||||
"flow": {
|
||||
"chunker:{id}": {
|
||||
"input": "persistent://tg/flow/chunk:{id}",
|
||||
"output": "persistent://tg/flow/chunk-load:{id}",
|
||||
"parameters": {
|
||||
"chunk_size": "{chunk-size}",
|
||||
"chunk_overlap": "{chunk-overlap}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`parameters` अनुभाग प्रवाह-विशिष्ट पैरामीटर नामों (कुंजियों) को पैरामीटर मेटाडेटा ऑब्जेक्ट्स से मैप करता है जिनमें शामिल हैं:
|
||||
`type`: केंद्रीय रूप से परिभाषित पैरामीटर परिभाषा का संदर्भ (उदाहरण के लिए, "llm-model")
|
||||
`description`: यूआई प्रदर्शन के लिए मानव-पठनीय विवरण
|
||||
`order`: पैरामीटर फ़ॉर्म के लिए प्रदर्शन क्रम (छोटे नंबर पहले दिखाई देते हैं)
|
||||
`advanced` (वैकल्पिक): एक बूलियन ध्वज जो इंगित करता है कि क्या यह एक उन्नत पैरामीटर है (डिफ़ॉल्ट: false)। जब इसे true पर सेट किया जाता है, तो यूआई डिफ़ॉल्ट रूप से इस पैरामीटर को छिपा सकता है या इसे "उन्नत" अनुभाग में रख सकता है
|
||||
<<<<<<< HEAD
|
||||
`controlled-by` (वैकल्पिक): एक अन्य पैरामीटर का नाम जो सरल मोड में इस पैरामीटर के मान को नियंत्रित करता है। जब निर्दिष्ट किया जाता है, तो यह पैरामीटर अपने मान को नियंत्रित पैरामीटर से प्राप्त करता है जब तक कि स्पष्ट रूप से ओवरराइड न किया जाए
|
||||
|
||||
यह दृष्टिकोण अनुमति देता है:
|
||||
कई प्रवाह ब्लूप्रिंट में पुन: प्रयोज्य पैरामीटर प्रकार परिभाषाएँ
|
||||
=======
|
||||
`controlled-by` (वैकल्पिक): एक अन्य पैरामीटर का नाम जो सरल मोड में इस पैरामीटर के मान को नियंत्रित करता है। जब निर्दिष्ट किया जाता है, तो यह पैरामीटर अपने मान को नियंत्रित पैरामीटर से विरासत में लेता है जब तक कि स्पष्ट रूप से ओवरराइड न किया जाए
|
||||
|
||||
यह दृष्टिकोण अनुमति देता है:
|
||||
कई फ़्लो ब्लूप्रिंट में पुन: प्रयोज्य पैरामीटर प्रकार परिभाषाएँ
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
केंद्रीकृत पैरामीटर प्रकार प्रबंधन और सत्यापन
|
||||
प्रवाह-विशिष्ट पैरामीटर विवरण और क्रम
|
||||
वर्णनात्मक पैरामीटर फ़ॉर्म के साथ बेहतर यूआई अनुभव
|
||||
प्रवाह में सुसंगत पैरामीटर सत्यापन
|
||||
नए मानक पैरामीटर प्रकारों को आसानी से जोड़ना
|
||||
बुनियादी/उन्नत मोड अलगाव के साथ सरलीकृत यूआई
|
||||
संबंधित सेटिंग्स के लिए पैरामीटर मान विरासत
|
||||
|
||||
<<<<<<< HEAD
|
||||
#### प्रवाह लॉन्च अनुरोध
|
||||
|
||||
प्रवाह लॉन्च एपीआई प्रवाह के पैरामीटर नामों का उपयोग करके पैरामीटर स्वीकार करता है:
|
||||
=======
|
||||
#### फ़्लो लॉन्च अनुरोध
|
||||
|
||||
फ़्लो लॉन्च एपीआई प्रवाह के पैरामीटर नामों का उपयोग करके पैरामीटर स्वीकार करता है:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
```json
|
||||
{
|
||||
"flow_class": "document-analysis",
|
||||
"flow_id": "customer-A-flow",
|
||||
"parameters": {
|
||||
"llm-model": "claude-3",
|
||||
"llm-temperature": 0.5,
|
||||
"chunk-size": 1024
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
ध्यान दें: इस उदाहरण में, `llm-rag-model` स्पष्ट रूप से प्रदान नहीं किया गया है, लेकिन यह `llm-model` से "claude-3" मान को अपने `controlled-by` संबंध के कारण प्राप्त करेगा। इसी तरह, `chunk-overlap` `chunk-size` के आधार पर गणना किए गए मान को प्राप्त कर सकता है।
|
||||
=======
|
||||
ध्यान दें: इस उदाहरण में, `llm-rag-model` स्पष्ट रूप से प्रदान नहीं किया गया है, लेकिन यह `llm-model` से "claude-3" मान को अपने `controlled-by` संबंध के कारण प्राप्त करेगा। इसी तरह, `chunk-overlap` `chunk-size` के आधार पर एक गणना किए गए मान को प्राप्त कर सकता है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
सिस्टम निम्नलिखित कार्य करेगा:
|
||||
1. फ्लो ब्लूप्रिंट परिभाषा से पैरामीटर मेटाडेटा निकालें
|
||||
2. फ्लो पैरामीटर नामों को उनके प्रकार परिभाषाओं (जैसे, `llm-model` → `llm-model` प्रकार) में मैप करें
|
||||
<<<<<<< HEAD
|
||||
3. नियंत्रित-द्वारा संबंधों को हल करें (जैसे, `llm-rag-model` `llm-model` से प्राप्त होता है)
|
||||
=======
|
||||
3. नियंत्रित-द्वारा (controlled-by) संबंधों को हल करें (जैसे, `llm-rag-model` `llm-model` से प्राप्त होता है)
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
4. पैरामीटर प्रकार परिभाषाओं के विरुद्ध उपयोगकर्ता द्वारा प्रदान किए गए और प्राप्त मूल्यों को मान्य करें
|
||||
5. फ्लो इंस्टेंशिएशन के दौरान हल किए गए मूल्यों को प्रोसेसर पैरामीटर में प्रतिस्थापित करें
|
||||
|
||||
### कार्यान्वयन विवरण
|
||||
|
||||
#### पैरामीटर रिज़ॉल्यूशन प्रक्रिया
|
||||
|
||||
जब कोई फ्लो शुरू होता है, तो सिस्टम निम्नलिखित पैरामीटर रिज़ॉल्यूशन चरण करता है:
|
||||
|
||||
1. **फ्लो ब्लूप्रिंट लोडिंग**: फ्लो ब्लूप्रिंट परिभाषा लोड करें और पैरामीटर मेटाडेटा निकालें
|
||||
2. **मेटाडेटा निष्कर्षण**: फ्लो ब्लूप्रिंट के `parameters` अनुभाग में परिभाषित प्रत्येक पैरामीटर के लिए `type`, `description`, `order`, `advanced`, और `controlled-by` निकालें
|
||||
3. **टाइप परिभाषा लुकअप**: फ्लो ब्लूप्रिंट में प्रत्येक पैरामीटर के लिए:
|
||||
<<<<<<< HEAD
|
||||
स्कीमा/कॉन्फ़िग स्टोर से `type` फ़ील्ड का उपयोग करके पैरामीटर प्रकार परिभाषा प्राप्त करें
|
||||
=======
|
||||
`type` फ़ील्ड का उपयोग करके स्कीमा/कॉन्फ़िग स्टोर से पैरामीटर प्रकार परिभाषा प्राप्त करें
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
प्रकार परिभाषाएँ कॉन्फ़िग सिस्टम में "parameter-type" प्रकार के साथ संग्रहीत की जाती हैं
|
||||
प्रत्येक प्रकार की परिभाषा में पैरामीटर का स्कीमा, डिफ़ॉल्ट मान और सत्यापन नियम होते हैं
|
||||
4. **डिफ़ॉल्ट मान रिज़ॉल्यूशन**:
|
||||
फ्लो ब्लूप्रिंट में परिभाषित प्रत्येक पैरामीटर के लिए:
|
||||
जांचें कि क्या उपयोगकर्ता ने इस पैरामीटर के लिए कोई मान प्रदान किया है
|
||||
यदि कोई उपयोगकर्ता मान प्रदान नहीं किया गया है, तो पैरामीटर प्रकार परिभाषा से `default` मान का उपयोग करें
|
||||
<<<<<<< HEAD
|
||||
उपयोगकर्ता द्वारा प्रदान किए गए और डिफ़ॉल्ट मानों दोनों को शामिल करते हुए एक पूर्ण पैरामीटर मानचित्र बनाएं
|
||||
=======
|
||||
उपयोगकर्ता द्वारा प्रदान किए गए और डिफ़ॉल्ट मानों दोनों को शामिल करते हुए एक पूर्ण पैरामीटर मैप बनाएं
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
5. **पैरामीटर इनहेरिटेंस रिज़ॉल्यूशन** (नियंत्रित-द्वारा संबंध):
|
||||
`controlled-by` फ़ील्ड वाले पैरामीटर के लिए, जांचें कि क्या कोई मान स्पष्ट रूप से प्रदान किया गया था
|
||||
यदि कोई स्पष्ट मान प्रदान नहीं किया गया है, तो नियंत्रित पैरामीटर से मान प्राप्त करें
|
||||
यदि नियंत्रित पैरामीटर में भी कोई मान नहीं है, तो प्रकार परिभाषा से डिफ़ॉल्ट का उपयोग करें
|
||||
जांचें कि `controlled-by` संबंधों में कोई गोलाकार निर्भरता मौजूद नहीं है
|
||||
6. **सत्यापन**: प्रकार परिभाषाओं के विरुद्ध पूर्ण पैरामीटर सेट (उपयोगकर्ता द्वारा प्रदान किए गए, डिफ़ॉल्ट और प्राप्त) को मान्य करें
|
||||
7. **भंडारण**: ऑडिटिंग के लिए फ्लो इंस्टेंस के साथ पूर्ण हल किए गए पैरामीटर सेट को संग्रहीत करें
|
||||
8. **टेम्प्लेट प्रतिस्थापन**: प्रोसेसर पैरामीटर में पैरामीटर प्लेसहोल्डर को हल किए गए मानों से बदलें
|
||||
9. **प्रोसेसर इंस्टेंशिएशन**: प्रतिस्थापित पैरामीटर के साथ प्रोसेसर बनाएं
|
||||
|
||||
**महत्वपूर्ण कार्यान्वयन नोट्स:**
|
||||
<<<<<<< HEAD
|
||||
फ्लो सर्विस को पैरामीटर प्रकार परिभाषाओं से डिफ़ॉल्ट के साथ उपयोगकर्ता द्वारा प्रदान किए गए पैरामीटर को मर्ज करना होगा
|
||||
पूर्ण पैरामीटर सेट (लागू डिफ़ॉल्ट सहित) को पता लगाने के लिए फ्लो के साथ संग्रहीत किया जाना चाहिए
|
||||
पैरामीटर रिज़ॉल्यूशन फ्लो शुरू होने के समय होता है, प्रोसेसर इंस्टेंशिएशन के समय नहीं
|
||||
=======
|
||||
फ्लो सेवा को उपयोगकर्ता द्वारा प्रदान किए गए पैरामीटर को पैरामीटर प्रकार परिभाषाओं से डिफ़ॉल्ट के साथ मर्ज करना होगा
|
||||
पूर्ण पैरामीटर सेट (लागू डिफ़ॉल्ट सहित) को ट्रेसबिलिटी के लिए फ्लो के साथ संग्रहीत किया जाना चाहिए
|
||||
पैरामीटर रिज़ॉल्यूशन फ्लो शुरू होने के समय होता है, न कि प्रोसेसर इंस्टेंशिएशन के समय
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
डिफ़ॉल्ट के बिना आवश्यक पैरामीटर गायब होने से फ्लो शुरू होने में विफलता होनी चाहिए, साथ ही एक स्पष्ट त्रुटि संदेश भी
|
||||
|
||||
#### नियंत्रित-द्वारा के साथ पैरामीटर इनहेरिटेंस
|
||||
|
||||
`controlled-by` फ़ील्ड पैरामीटर मान इनहेरिटेंस को सक्षम करता है, जो उपयोगकर्ता इंटरफ़ेस को सरल बनाने के साथ-साथ लचीलापन बनाए रखने के लिए विशेष रूप से उपयोगी है:
|
||||
|
||||
**उदाहरण परिदृश्य**:
|
||||
`llm-model` पैरामीटर प्राथमिक LLM मॉडल को नियंत्रित करता है
|
||||
`llm-rag-model` पैरामीटर में `"controlled-by": "llm-model"` होता है
|
||||
सरल मोड में, `llm-model` को "gpt-4" पर सेट करने से स्वचालित रूप से `llm-rag-model` भी "gpt-4" पर सेट हो जाता है
|
||||
उन्नत मोड में, उपयोगकर्ता `llm-rag-model` को एक अलग मान के साथ ओवरराइड कर सकते हैं
|
||||
|
||||
**रिज़ॉल्यूशन नियम**:
|
||||
1. यदि किसी पैरामीटर में एक स्पष्ट रूप से प्रदान किया गया मान है, तो उस मान का उपयोग करें
|
||||
2. यदि कोई स्पष्ट मान नहीं है और `controlled-by` सेट है, तो नियंत्रित पैरामीटर का मान उपयोग करें
|
||||
3. यदि नियंत्रित पैरामीटर में कोई मान नहीं है, तो प्रकार परिभाषा से डिफ़ॉल्ट पर वापस जाएं
|
||||
4. `controlled-by` संबंधों में गोलाकार निर्भरताएँ एक सत्यापन त्रुटि का कारण बनती हैं
|
||||
|
||||
**UI व्यवहार**:
|
||||
बुनियादी/सरल मोड में: `controlled-by` वाले पैरामीटर छिपे हो सकते हैं या प्राप्त मान के साथ केवल-पढ़ने योग्य के रूप में दिखाए जा सकते हैं
|
||||
उन्नत मोड में: सभी पैरामीटर दिखाए जाते हैं और उन्हें व्यक्तिगत रूप से कॉन्फ़िगर किया जा सकता है
|
||||
जब एक नियंत्रित पैरामीटर बदलता है, तो निर्भर पैरामीटर स्वचालित रूप से अपडेट हो जाते हैं जब तक कि उन्हें स्पष्ट रूप से ओवरराइड न किया जाए
|
||||
|
||||
#### पल्सर एकीकरण
|
||||
|
||||
1. **स्टार्ट-फ्लो ऑपरेशन**
|
||||
<<<<<<< HEAD
|
||||
पल्सर स्टार्ट-फ्लो ऑपरेशन को एक `parameters` फ़ील्ड स्वीकार करना होगा जिसमें पैरामीटर मानों का एक मानचित्र होता है
|
||||
=======
|
||||
पल्सर स्टार्ट-फ्लो ऑपरेशन को एक `parameters` फ़ील्ड स्वीकार करना होगा जिसमें पैरामीटर मानों का एक मैप हो
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
स्टार्ट-फ्लो अनुरोध के लिए पल्सर स्कीमा को वैकल्पिक `parameters` फ़ील्ड को शामिल करने के लिए अपडेट किया जाना चाहिए
|
||||
उदाहरण अनुरोध:
|
||||
```json
|
||||
{
|
||||
"flow_class": "document-analysis",
|
||||
"flow_id": "customer-A-flow",
|
||||
"parameters": {
|
||||
"model": "claude-3",
|
||||
"size": "12b",
|
||||
"temp": 0.5,
|
||||
"chunk": 1024
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **गेट-फ्लो ऑपरेशन**
|
||||
गेट-फ्लो प्रतिक्रिया के लिए पल्सर स्कीमा को `parameters` फ़ील्ड को शामिल करने के लिए अपडेट किया जाना चाहिए।
|
||||
यह ग्राहकों को उन पैरामीटर मानों को पुनः प्राप्त करने की अनुमति देता है जिनका उपयोग फ्लो शुरू करते समय किया गया था।
|
||||
उदाहरण प्रतिक्रिया:
|
||||
```json
|
||||
{
|
||||
"flow_id": "customer-A-flow",
|
||||
"flow_class": "document-analysis",
|
||||
"status": "running",
|
||||
"parameters": {
|
||||
"model": "claude-3",
|
||||
"size": "12b",
|
||||
"temp": 0.5,
|
||||
"chunk": 1024
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### फ्लो सर्विस कार्यान्वयन
|
||||
|
||||
फ्लो कॉन्फ़िगरेशन सर्विस (`trustgraph-flow/trustgraph/config/service/flow.py`) को निम्नलिखित सुधारों की आवश्यकता है:
|
||||
|
||||
1. **पैरामीटर रिज़ॉल्यूशन फ़ंक्शन**
|
||||
```python
|
||||
async def resolve_parameters(self, flow_class, user_params):
|
||||
"""
|
||||
Resolve parameters by merging user-provided values with defaults.
|
||||
|
||||
Args:
|
||||
flow_class: The flow blueprint definition dict
|
||||
user_params: User-provided parameters dict
|
||||
|
||||
Returns:
|
||||
Complete parameter dict with user values and defaults merged
|
||||
"""
|
||||
```
|
||||
|
||||
यह फ़ंक्शन को इस प्रकार होना चाहिए:
|
||||
फ़्लो ब्लूप्रिंट के `parameters` अनुभाग से पैरामीटर मेटाडेटा निकालें
|
||||
प्रत्येक पैरामीटर के लिए, कॉन्फ़िगरेशन स्टोर से इसके प्रकार की परिभाषा प्राप्त करें
|
||||
उन सभी पैरामीटर के लिए डिफ़ॉल्ट मान लागू करें जो उपयोगकर्ता द्वारा प्रदान नहीं किए गए हैं
|
||||
`controlled-by` विरासत संबंधों को संभालें
|
||||
<<<<<<< HEAD
|
||||
संपूर्ण पैरामीटर सेट लौटाएं
|
||||
|
||||
2. **संशोधित `handle_start_flow` विधि**
|
||||
फ़्लो ब्लूप्रिंट लोड करने के बाद `resolve_parameters` को कॉल करें
|
||||
टेम्पलेट प्रतिस्थापन के लिए पूरे हल किए गए पैरामीटर सेट का उपयोग करें
|
||||
पूरे पैरामीटर सेट को (केवल उपयोगकर्ता द्वारा प्रदान किए गए नहीं) फ़्लो के साथ संग्रहीत करें
|
||||
=======
|
||||
पूर्ण पैरामीटर सेट लौटाएं
|
||||
|
||||
2. **संशोधित `handle_start_flow` विधि**
|
||||
फ़्लो ब्लूप्रिंट लोड करने के बाद `resolve_parameters` को कॉल करें
|
||||
टेम्पलेट प्रतिस्थापन के लिए पूर्ण हल किए गए पैरामीटर सेट का उपयोग करें
|
||||
पूर्ण पैरामीटर सेट (केवल उपयोगकर्ता द्वारा प्रदान किए गए नहीं) को फ़्लो के साथ संग्रहीत करें
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
सत्यापित करें कि सभी आवश्यक पैरामीटर में मान हैं
|
||||
|
||||
3. **पैरामीटर प्रकार प्राप्त करना**
|
||||
पैरामीटर प्रकार की परिभाषाएँ "parameter-type" प्रकार के साथ कॉन्फ़िगर में संग्रहीत हैं
|
||||
प्रत्येक प्रकार की परिभाषा में स्कीमा, डिफ़ॉल्ट मान और सत्यापन नियम होते हैं
|
||||
अक्सर उपयोग किए जाने वाले पैरामीटर प्रकारों को कैश करें ताकि कॉन्फ़िगर लुकअप कम हो सकें
|
||||
|
||||
#### कॉन्फ़िगर सिस्टम एकीकरण
|
||||
|
||||
3. **फ़्लो ऑब्जेक्ट स्टोरेज**
|
||||
जब कोई फ़्लो घटक कॉन्फ़िगर प्रबंधक में कॉन्फ़िगर सिस्टम में जोड़ा जाता है, तो फ़्लो ऑब्जेक्ट में हल किए गए पैरामीटर मान शामिल होने चाहिए
|
||||
<<<<<<< HEAD
|
||||
कॉन्फ़िगर प्रबंधक को मूल उपयोगकर्ता-प्रदान किए गए पैरामीटर और हल किए गए मान दोनों (डिफ़ॉल्ट लागू किए गए) को संग्रहीत करने की आवश्यकता होती है
|
||||
कॉन्फ़िगर सिस्टम में फ़्लो ऑब्जेक्ट में शामिल होना चाहिए:
|
||||
=======
|
||||
कॉन्फ़िगर प्रबंधक को मूल उपयोगकर्ता-प्रदान किए गए पैरामीटर और हल किए गए मान (डिफ़ॉल्ट लागू होने के साथ) दोनों को संग्रहीत करने की आवश्यकता है
|
||||
कॉन्फ़िगर सिस्टम में फ़्लो ऑब्जेक्ट में निम्नलिखित शामिल होने चाहिए:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
`parameters`: फ़्लो के लिए उपयोग किए गए अंतिम हल किए गए पैरामीटर मान
|
||||
|
||||
#### CLI एकीकरण
|
||||
|
||||
4. **लाइब्रेरी CLI कमांड**
|
||||
फ़्लो शुरू करने वाले CLI कमांड में पैरामीटर समर्थन होना चाहिए:
|
||||
कमांड-लाइन फ़्लैग या कॉन्फ़िगरेशन फ़ाइलों के माध्यम से पैरामीटर मान स्वीकार करें
|
||||
सबमिशन से पहले फ़्लो ब्लूप्रिंट परिभाषाओं के विरुद्ध पैरामीटर को मान्य करें
|
||||
जटिल पैरामीटर सेट के लिए पैरामीटर फ़ाइल इनपुट (JSON/YAML) का समर्थन करें
|
||||
|
||||
फ़्लो दिखाने वाले CLI कमांड में पैरामीटर जानकारी प्रदर्शित करने की आवश्यकता होती है:
|
||||
उस समय प्रदर्शित करें जब फ़्लो शुरू किया गया था, तो उपयोग किए गए पैरामीटर मान
|
||||
एक फ़्लो ब्लूप्रिंट के लिए उपलब्ध पैरामीटर प्रदर्शित करें
|
||||
पैरामीटर सत्यापन स्कीमा और डिफ़ॉल्ट प्रदर्शित करें
|
||||
|
||||
#### प्रोसेसर बेस क्लास एकीकरण
|
||||
|
||||
5. **पैरामीटरस्पेक समर्थन**
|
||||
प्रोसेसर बेस क्लास को मौजूदा पैरामीटर्सस्पेक तंत्र के माध्यम से पैरामीटर प्रतिस्थापन का समर्थन करने की आवश्यकता है
|
||||
पैरामीटर्सस्पेक क्लास (उपभोक्तास्पेक और प्रोड्यूसरस्पेक के समान मॉड्यूल में स्थित) को पैरामीटर टेम्पलेट प्रतिस्थापन का समर्थन करने के लिए आवश्यक होने पर बढ़ाया जाना चाहिए
|
||||
<<<<<<< HEAD
|
||||
प्रोसेसर को अपने पैरामीटर को कॉन्फ़िगर करने के लिए पैरामीटर्सस्पेक को कॉल करने में सक्षम होना चाहिए, जिसमें फ़्लो लॉन्च समय पर हल किए गए पैरामीटर मान शामिल हैं
|
||||
=======
|
||||
प्रोसेसर को अपने पैरामीटर को कॉन्फ़िगर करने के लिए पैरामीटर्सस्पेक को लागू करने में सक्षम होना चाहिए, जिसमें फ़्लो लॉन्च समय पर हल किए गए पैरामीटर मान शामिल हैं
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
पैरामीटर्सस्पेक कार्यान्वयन को:
|
||||
पैरामीटर कॉन्फ़िगरेशन स्वीकार करें जिसमें पैरामीटर प्लेसहोल्डर शामिल हैं (जैसे, `{model}`, `{temperature}`)
|
||||
प्रोसेसर के इंस्टेंट होने पर रनटाइम पैरामीटर प्रतिस्थापन का समर्थन करें
|
||||
सत्यापित करें कि प्रतिस्थापित मान अपेक्षित प्रकार और बाधाओं से मेल खाते हैं
|
||||
गुम या अमान्य पैरामीटर संदर्भों के लिए त्रुटि हैंडलिंग प्रदान करें
|
||||
|
||||
#### प्रतिस्थापन नियम
|
||||
|
||||
<<<<<<< HEAD
|
||||
प्रोसेसर पैरामीटर में पैरामीटर `{parameter-name}` प्रारूप का उपयोग करते हैं
|
||||
=======
|
||||
पैरामीटर प्रोसेसर पैरामीटर में `{parameter-name}` प्रारूप का उपयोग करते हैं
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
पैरामीटर में पैरामीटर नाम फ़्लो के `parameters` अनुभाग में कुंजियों से मेल खाते हैं
|
||||
प्रतिस्थापन `{id}` और `{class}` प्रतिस्थापन के साथ-साथ होता है
|
||||
अमान्य पैरामीटर संदर्भ लॉन्च-टाइम त्रुटियों का परिणाम देते हैं
|
||||
केंद्रीय रूप से संग्रहीत पैरामीटर परिभाषा के आधार पर प्रकार सत्यापन होता है
|
||||
**महत्वपूर्ण**: सभी पैरामीटर मान स्ट्रिंग के रूप में संग्रहीत और प्रसारित किए जाते हैं
|
||||
संख्याओं को स्ट्रिंग में परिवर्तित किया जाता है (जैसे, `0.7` `"0.7"` बन जाता है)
|
||||
बूलियन को लोअरकेस स्ट्रिंग में परिवर्तित किया जाता है (जैसे, `true` `"true"` बन जाता है)
|
||||
<<<<<<< HEAD
|
||||
यह पल्सर स्कीमा की आवश्यकता है जो `parameters = Map(String())` को परिभाषित करती है
|
||||
=======
|
||||
यह पल्सर स्कीमा द्वारा आवश्यक है जो `parameters = Map(String())` को परिभाषित करता है
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
उदाहरण समाधान:
|
||||
```
|
||||
Flow parameter mapping: "model": "llm-model"
|
||||
Processor parameter: "model": "{model}"
|
||||
User provides: "model": "gemma3:8b"
|
||||
Final parameter: "model": "gemma3:8b"
|
||||
|
||||
Example with type conversion:
|
||||
Parameter type default: 0.7 (number)
|
||||
Stored in flow: "0.7" (string)
|
||||
Substituted in processor: "0.7" (string)
|
||||
```
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
पैरामीटर स्कीमा सत्यापन के लिए यूनिट परीक्षण
|
||||
प्रोसेसर पैरामीटर में पैरामीटर प्रतिस्थापन के लिए एकीकरण परीक्षण
|
||||
विभिन्न पैरामीटर मानों के साथ फ्लो लॉन्च करने के लिए एंड-टू-एंड परीक्षण
|
||||
पैरामीटर फॉर्म पीढ़ी और सत्यापन के लिए यूआई परीक्षण
|
||||
कई पैरामीटर वाले फ्लो के लिए प्रदर्शन परीक्षण
|
||||
किनारे के मामले: गुम पैरामीटर, अमान्य प्रकार, अपरिभाषित पैरामीटर संदर्भ
|
||||
|
||||
## माइग्रेशन योजना
|
||||
|
||||
1. सिस्टम को बिना पैरामीटर वाले फ्लो ब्लूप्रिंट का समर्थन करना जारी रखना चाहिए।
|
||||
घोषित।
|
||||
2. सिस्टम को बिना पैरामीटर वाले फ्लो का समर्थन करना जारी रखना चाहिए:
|
||||
<<<<<<< HEAD
|
||||
यह बिना पैरामीटर वाले फ्लो और पैरामीटर वाले फ्लो दोनों के लिए काम करता है (उनके पास डिफ़ॉल्ट होते हैं)।
|
||||
=======
|
||||
यह बिना पैरामीटर वाले फ्लो और पैरामीटर वाले फ्लो दोनों के लिए काम करता है (उनके पास डिफ़ॉल्ट मान होते हैं)।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## खुले प्रश्न
|
||||
|
||||
|
||||
<<<<<<< HEAD
|
||||
प्रश्न: क्या पैरामीटर जटिल, नेस्टेड ऑब्जेक्ट्स का समर्थन करेंगे, या केवल साधारण प्रकारों तक सीमित रहेंगे?
|
||||
उत्तर: पैरामीटर मान स्ट्रिंग के रूप में एन्कोड किए जाएंगे, इसलिए शायद हमें
|
||||
केवल स्ट्रिंग तक ही सीमित रहना चाहिए।
|
||||
|
||||
प्रश्न: क्या पैरामीटर प्लेसहोल्डर को कतार के नामों में अनुमति दी जानी चाहिए, या केवल
|
||||
पैरामीटर में?
|
||||
उत्तर: केवल पैरामीटर में, ताकि अजीब इंजेक्शन और असामान्य स्थितियों से बचा जा सके।
|
||||
|
||||
प्रश्न: पैरामीटर नामों और सिस्टम वेरिएबल्स के बीच टकराव को कैसे संभालें, जैसे कि
|
||||
`id` और `class`?
|
||||
अ: यह सही नहीं है कि फ्लो शुरू करते समय आईडी और क्लास दोनों निर्दिष्ट किए जाएं।
|
||||
|
||||
प्रश्न: क्या हमें गणना किए गए पैरामीटर (अन्य पैरामीटर से प्राप्त) का समर्थन करना चाहिए?
|
||||
=======
|
||||
प्रश्न: क्या पैरामीटर जटिल, नेस्टेड ऑब्जेक्ट्स का समर्थन करेंगे, या केवल सरल प्रकारों तक सीमित रहेंगे?
|
||||
उत्तर: पैरामीटर मान स्ट्रिंग के रूप में एन्कोड किए जाएंगे, इसलिए हम शायद केवल स्ट्रिंग तक ही सीमित रहना चाहेंगे।
|
||||
|
||||
|
||||
प्रश्न: क्या पैरामीटर प्लेसहोल्डर को कतार के नामों में अनुमति दी जानी चाहिए, या केवल पैरामीटर में?
|
||||
उत्तर: केवल पैरामीटर में, ताकि अजीब इंजेक्शन और असामान्य स्थितियों से बचा जा सके।
|
||||
|
||||
|
||||
प्रश्न: पैरामीटर नामों और सिस्टम वेरिएबल्स के बीच टकराव को कैसे संभालें, जैसे कि
|
||||
`id` और `class`?
|
||||
अ: यह सही नहीं है कि फ्लो शुरू करते समय आईडी और क्लास दोनों को निर्दिष्ट किया जाए।
|
||||
|
||||
प्रश्न: क्या हमें गणना किए गए मापदंडों (अन्य मापदंडों से प्राप्त) का समर्थन करना चाहिए?
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
उत्तर: केवल स्ट्रिंग प्रतिस्थापन का उपयोग करके अजीब इंजेक्शन और विशेष मामलों को हटाना।
|
||||
|
||||
## संदर्भ
|
||||
|
||||
JSON स्कीमा विनिर्देश: https://json-schema.org/
|
||||
फ्लो ब्लूप्रिंट परिभाषा विनिर्देश: docs/tech-specs/flow-class-definition.md
|
||||
376
docs/tech-specs/hi/graph-contexts.hi.md
Normal file
376
docs/tech-specs/hi/graph-contexts.hi.md
Normal file
|
|
@ -0,0 +1,376 @@
|
|||
---
|
||||
layout: default
|
||||
title: "ग्राफ संदर्भ तकनीकी विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# ग्राफ संदर्भ तकनीकी विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह विनिर्देश ट्रस्टग्राफ के मुख्य ग्राफ प्रिमिटिव में किए गए परिवर्तनों का वर्णन करता है ताकि
|
||||
यह RDF 1.2 के अनुरूप हो और RDF डेटासेट के पूर्ण अर्थों का समर्थन कर सके। यह 2.x रिलीज़ श्रृंखला के लिए एक महत्वपूर्ण बदलाव है।
|
||||
|
||||
### संस्करण
|
||||
|
||||
- **2.0**: प्रारंभिक अपनाने वाला रिलीज़। मुख्य विशेषताएं उपलब्ध हैं, लेकिन यह पूरी तरह से
|
||||
उत्पादन के लिए तैयार नहीं हो सकता है।
|
||||
- **2.1 / 2.2**: उत्पादन रिलीज़। स्थिरता और पूर्णता की पुष्टि की गई है।
|
||||
|
||||
परिपक्वता में लचीलापन जानबूझकर रखा गया है - प्रारंभिक अपनाने वाले नई
|
||||
क्षमताओं तक पहुंच सकते हैं, भले ही सभी विशेषताएं उत्पादन के लिए पूरी तरह से तैयार न हों।
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
इस कार्य के प्राथमिक लक्ष्य तथ्यों/कथनों के बारे में मेटाडेटा को सक्षम करना हैं:
|
||||
|
||||
- **टेम्पोरल जानकारी**: तथ्यों को समय मेटाडेटा से जोड़ना
|
||||
- जब किसी तथ्य को सत्य माना गया था
|
||||
- जब कोई तथ्य सत्य हो गया
|
||||
- जब किसी तथ्य को गलत साबित किया गया
|
||||
|
||||
- **उत्पत्ति/स्रोत**: यह ट्रैक करना कि कौन से स्रोत किसी तथ्य का समर्थन करते हैं
|
||||
- "यह तथ्य स्रोत X द्वारा समर्थित था"
|
||||
- तथ्यों को उनके मूल दस्तावेजों से जोड़ना
|
||||
|
||||
- **सत्यता/विश्वसनीयता**: सत्य के बारे में दावे रिकॉर्ड करना
|
||||
- "व्यक्ति P ने कहा कि यह सत्य था"
|
||||
- "व्यक्ति Q का दावा है कि यह गलत है"
|
||||
- विश्वास स्कोरिंग और संघर्ष का पता लगाने को सक्षम करना
|
||||
|
||||
**परिकल्पना**: पुन:पुनर्बलन (RDF-स्टार / उद्धृत ट्रिपल) वह प्रमुख तंत्र है
|
||||
इन परिणामों को प्राप्त करने के लिए, क्योंकि सभी को कथनों के बारे में कथन करने की आवश्यकता होती है।
|
||||
|
||||
## पृष्ठभूमि
|
||||
|
||||
"यह तथ्य (एलिस बॉब को जानती है) 15 जनवरी, 2024 को खोजा गया था" या
|
||||
"स्रोत X दावे (Y कारण Z है) का समर्थन करता है" को व्यक्त करने के लिए, आपको एक किनारे
|
||||
का संदर्भ देना होगा जिसे आप कथनों के बारे में बात कर सकते हैं। मानक ट्रिपल इसका समर्थन नहीं करते हैं।
|
||||
|
||||
### वर्तमान सीमाएं
|
||||
|
||||
`trustgraph-base/trustgraph/schema/core/primitives.py` में वर्तमान `Value` वर्ग:
|
||||
- URI नोड (`is_uri=True`)
|
||||
- शाब्दिक मान (`is_uri=False`)
|
||||
|
||||
`type` फ़ील्ड मौजूद है, लेकिन इसका उपयोग XSD डेटा प्रकारों को दर्शाने के लिए नहीं किया जाता है।
|
||||
|
||||
## तकनीकी डिज़ाइन
|
||||
|
||||
### समर्थित RDF विशेषताएं
|
||||
|
||||
#### मुख्य विशेषताएं (पुन:पुनर्बलन लक्ष्यों से संबंधित)
|
||||
|
||||
ये विशेषताएं अस्थायी, उत्पत्ति और सत्यता लक्ष्यों से सीधे संबंधित हैं:
|
||||
|
||||
1. **RDF 1.2 उद्धृत ट्रिपल (RDF-स्टार)**
|
||||
- किनारे जो अन्य किनारों की ओर इशारा करते हैं
|
||||
- एक ट्रिपल एक ट्रिपल के विषय या वस्तु दोनों के रूप में दिखाई दे सकता है
|
||||
- कथनों के बारे में कथन सक्षम करें (पुन:पुनर्बलन)
|
||||
- व्यक्तिगत तथ्यों को एनोटेट करने का मुख्य तंत्र
|
||||
|
||||
2. **RDF डेटासेट / नामित ग्राफ**
|
||||
- एक डेटासेट के भीतर कई नामित ग्राफ का समर्थन
|
||||
- प्रत्येक ग्राफ को एक IRI द्वारा पहचाना जाता है
|
||||
- ट्रिपल (s, p, o) से क्वाड (s, p, o, g) में बदलाव
|
||||
- एक डिफ़ॉल्ट ग्राफ प्लस शून्य या अधिक नामित ग्राफ शामिल हैं
|
||||
- ग्राफ IRI कथनों में एक विषय हो सकता है, उदाहरण के लिए:
|
||||
```
|
||||
<graph-source-A> <discoveredOn> "2024-01-15"
|
||||
<graph-source-A> <hasVeracity> "उच्च"
|
||||
```
|
||||
- ध्यान दें: नामित ग्राफ पुन:पुनर्बलन से अलग विशेषता है। उनके
|
||||
कथन एनोटेशन (विभाजन, एक्सेस नियंत्रण, डेटासेट संगठन) से परे उपयोग हैं
|
||||
और इसे एक अलग क्षमता के रूप में माना जाना चाहिए।
|
||||
|
||||
3. **रिक्त नोड** (सीमित समर्थन)
|
||||
- वैश्विक URI के बिना अनाम नोड
|
||||
- बाहरी RDF डेटा लोड करते समय संगतता के लिए समर्थित
|
||||
- **सीमित स्थिति**: लोडिंग के बाद स्थिर पहचान की कोई गारंटी नहीं
|
||||
- वाइल्डकार्ड प्रश्नों के माध्यम से उनका पता लगाएं (कनेक्शन से मिलान करें, आईडी से नहीं)
|
||||
- यह पहली श्रेणी की विशेषता नहीं है - सटीक रिक्त नोड हैंडलिंग पर भरोसा न करें।
|
||||
|
||||
#### अवसरवादी सुधार (2.0 ब्रेकिंग परिवर्तन)
|
||||
|
||||
ये विशेषताएं पुन:पुनर्बलन लक्ष्यों से सीधे संबंधित नहीं हैं, लेकिन
|
||||
महत्वपूर्ण सुधार हैं जिन्हें ब्रेकिंग परिवर्तनों के दौरान शामिल किया जाना चाहिए:
|
||||
|
||||
4. **शाब्दिक डेटा प्रकार**
|
||||
- XSD डेटा प्रकारों के लिए `type` फ़ील्ड का ठीक से उपयोग करें
|
||||
- उदाहरण: xsd:string, xsd:integer, xsd:dateTime, आदि।
|
||||
- वर्तमान सीमा को ठीक करता है: तिथियों या पूर्णांकों को ठीक से दर्शाया नहीं जा सकता है।
|
||||
|
||||
5. **भाषा टैग**
|
||||
- स्ट्रिंग शाब्दिक पर भाषा विशेषताओं का समर्थन
|
||||
- ध्यान दें: एक शाब्दिक में या तो एक भाषा टैग होता है या एक डेटा प्रकार, दोनों नहीं
|
||||
(rdf:langString को छोड़कर)
|
||||
- AI/बहुभाषी उपयोग के मामलों के लिए महत्वपूर्ण।
|
||||
|
||||
### डेटा मॉडल
|
||||
|
||||
#### टर्म (नाम बदलकर वैल्यू)
|
||||
|
||||
`Value` वर्ग को बेहतर ढंग से RDF शब्दावली को दर्शाने के लिए `Term` में बदल दिया जाएगा।
|
||||
इस नामकरण का दो उद्देश्य हैं:
|
||||
1. यह नामकरण RDF अवधारणाओं के साथ संरेखित होता है (एक "टर्म" एक IRI, शाब्दिक,
|
||||
रिक्त नोड या उद्धृत ट्रिपल हो सकता है - केवल एक "मान" नहीं)।
|
||||
2. यह ब्रेकिंग परिवर्तन इंटरफ़ेस पर कोड समीक्षा को मजबूर करता है - कोई भी कोड जो अभी भी
|
||||
`Value` को संदर्भित करता है, वह स्पष्ट रूप से टूटा हुआ है और इसे अपडेट करने की आवश्यकता है।
|
||||
|
||||
एक टर्म का प्रतिनिधित्व किया जा सकता है:
|
||||
|
||||
- **IRI/URI**: एक नामित नोड/संसाधन
|
||||
- **रिक्त नोड**: स्थानीय दायरे वाला एक अनाम नोड
|
||||
- **शाब्दिक**: एक डेटा मान जिसमें या तो:
|
||||
- एक डेटा प्रकार (XSD प्रकार), या
|
||||
- एक भाषा टैग
|
||||
- **उद्धृत ट्रिपल**: एक ट्रिपल का उपयोग एक टर्म के रूप में किया जाता है (RDF 1.2)
|
||||
|
||||
##### चुनी गई दृष्टिकोण: एकल वर्ग जिसमें प्रकार विभेदक है
|
||||
|
||||
सीरियलाइज़ेशन आवश्यकताएं संरचना को चलाती हैं - वायर प्रारूप में एक प्रकार विभेदक की आवश्यकता होती है
|
||||
चाहे पायथन प्रतिनिधित्व कुछ भी हो। एक एकल वर्ग जिसमें एक प्रकार फ़ील्ड प्राकृतिक है
|
||||
और वर्तमान `Value` पैटर्न के साथ संरेखित है।
|
||||
|
||||
एकल-अक्षर प्रकार कोड कॉम्पैक्ट सीरियलाइज़ेशन प्रदान करते हैं:
|
||||
|
||||
```python
|
||||
from dataclasses import dataclass
|
||||
|
||||
# टर्म प्रकार स्थिरांक
|
||||
IRI = "i" # IRI/URI नोड
|
||||
BLANK = "b" # रिक्त नोड
|
||||
LITERAL = "l" # शाब्दिक मान
|
||||
TRIPLE = "t" # उद्धृत ट्रिपल (RDF-स्टार)
|
||||
|
||||
@dataclass
|
||||
class Term:
|
||||
type: str = "" # इनमें से एक: IRI, BLANK, LITERAL, TRIPLE
|
||||
|
||||
# IRI टर्म के लिए (type == IRI)
|
||||
iri: str = ""
|
||||
|
||||
# रिक्त नोड के लिए (type == BLANK)
|
||||
id: str = ""
|
||||
|
||||
# शाब्दिक के लिए (type == LITERAL)
|
||||
value: str = ""
|
||||
datatype: str = "" # XSD डेटा प्रकार URI (भाषा के साथ परस्पर अनन्य)
|
||||
language: str = "" # भाषा टैग (डेटा प्रकार के साथ परस्पर अनन्य)
|
||||
|
||||
# उद्धृत ट्रिपल के लिए (type == TRIPLE)
|
||||
triple: "Triple | None" = None
|
||||
```
|
||||
|
||||
उपयोग के उदाहरण:
|
||||
|
||||
```python
|
||||
# IRI टर्म
|
||||
node = Term(type=IRI, iri="http://example.org/Alice")
|
||||
|
||||
# डेटा प्रकार के साथ शाब्दिक
|
||||
age = Term(type=LITERAL, value="42", datatype="xsd:integer")
|
||||
|
||||
# भाषा टैग के साथ शाब्दिक
|
||||
label = Term(type=LITERAL, value="नमस्ते", language="en")
|
||||
|
||||
# रिक्त नोड
|
||||
anon = Term(type=BLANK, id="_:b1")
|
||||
|
||||
# उद्धृत ट्रिपल (कथन के बारे में कथन)
|
||||
inner = Triple(
|
||||
s=Term(type=IRI, iri="http://example.org/Alice"),
|
||||
p=Term(type=IRI, iri="http://example.org/knows"),
|
||||
o=Term(type=IRI, iri="http://example.org/Bob"),
|
||||
)
|
||||
reified = Term(type=TRIPLE, triple=inner)
|
||||
```
|
||||
|
||||
##### विचार किए गए विकल्प
|
||||
|
||||
**विकल्प B: विशिष्ट वर्गों का संघ** (`Term = IRI | BlankNode | Literal | QuotedTriple`)
|
||||
- अस्वीकृत: सीरियलाइज़ेशन को अभी भी एक प्रकार विभेदक की आवश्यकता होगी, जो जटिलता जोड़ता है।
|
||||
|
||||
**विकल्प C: बेस क्लास जिसमें सबक्लासेस हैं**
|
||||
- अस्वीकृत: समान सीरियलाइज़ेशन समस्या, साथ ही डेटा क्लास इनहेरिटेंस की जटिलताएं।
|
||||
|
||||
#### ट्रिपल / क्वाड
|
||||
|
||||
`Triple` वर्ग में एक वैकल्पिक ग्राफ फ़ील्ड है ताकि यह क्वाड बन जाए:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class Triple:
|
||||
s: Term | None = None # विषय
|
||||
p: Term | None = None # विधेय
|
||||
o: Term | None = None # वस्तु
|
||||
g: str | None = None # ग्राफ नाम (IRI), None = डिफ़ॉल्ट ग्राफ
|
||||
```
|
||||
|
||||
डिज़ाइन निर्णय:
|
||||
- **फ़ील्ड नाम**: स्थिरता के लिए `g` को `s`, `p`, `o` के साथ
|
||||
- **वैकल्पिक**: `None` का मतलब डिफ़ॉल्ट ग्राफ (अनटैग)
|
||||
- **प्रकार**: पूर्ण `Term` तंत्र की आवश्यकता नहीं होने के कारण, केवल एक स्ट्रिंग (IRI)
|
||||
- ग्राफ नाम हमेशा IRI होते हैं
|
||||
- ग्राफ नाम के रूप में रिक्त नोड को खारिज कर दिया गया (बहुत भ्रमित करने वाला)
|
||||
|
||||
ध्यान दें: `Triple` वर्ग का नाम `Quad` होने पर भी `Triple` रहता है।
|
||||
यह अपव्यय से बचाता है और "ट्रिपल" अभी भी सामान्य शब्दावली है। ग्राफ संदर्भ
|
||||
यह दर्शाता है कि ट्रिपल कहाँ स्थित है।
|
||||
|
||||
### उम्मीदवार क्वेरी पैटर्न
|
||||
|
||||
वर्तमान क्वेरी इंजन S, P, O टर्म के संयोजनों को स्वीकार करता है। उद्धृत
|
||||
ट्रिपल के साथ, एक ट्रिपल स्वयं उन स्थितियों में एक मान्य टर्म बन जाता है। नीचे
|
||||
उम्मीदवार क्वेरी पैटर्न दिए गए हैं जो मूल लक्ष्यों का समर्थन करते हैं।
|
||||
|
||||
#### ग्राफ पैरामीटर अर्थशास्त्र
|
||||
|
||||
पिछड़ी संगतता के लिए SPARQL सम्मेलनों का पालन करना:
|
||||
|
||||
- **`g` छोड़ा गया / None**: केवल डिफ़ॉल्ट ग्राफ क्वेरी करें
|
||||
- **`g` = विशिष्ट IRI**: केवल उस नामित ग्राफ को क्वेरी करें
|
||||
- **`g` = वाइल्डकार्ड / `*`**: सभी ग्राफों में क्वेरी करें (SPARQL के बराबर
|
||||
`GRAPH ?g { ... }`)
|
||||
|
||||
यह सरल क्वेरी को सरल रखता है और नामित ग्राफ क्वेरी को वैकल्पिक बनाता है।
|
||||
|
||||
क्रॉस-ग्राफ क्वेरी (g=वाइल्डकार्ड) पूरी तरह से समर्थित हैं। Cassandra स्कीमा
|
||||
समर्पित तालिकाओं को शामिल करता है (SPOG, POSG, OSPG) जहां g एक क्लस्टरिंग कॉलम है
|
||||
विभिन्न ग्राफों में कुशल क्वेरी सक्षम करने के लिए पार्टीशन कुंजी नहीं है।
|
||||
|
||||
#### टेम्पोरल क्वेरी
|
||||
|
||||
**एक निश्चित तिथि के बाद खोजे गए सभी तथ्यों का पता लगाएं:**
|
||||
```
|
||||
S: ? # कोई भी उद्धृत ट्रिपल
|
||||
P: <discoveredOn>
|
||||
O: > "2024-01-15"^^xsd:date # तिथि तुलना
|
||||
```
|
||||
|
||||
**पता लगाएं कि किसी विशिष्ट तथ्य को कब सत्य माना गया था:**
|
||||
```
|
||||
S: << <एलिस> <जानता है> <बॉब> >> # विषय के रूप में उद्धृत ट्रिपल
|
||||
P: <believedTrueFrom>
|
||||
O: ? # तिथि लौटाता है
|
||||
```
|
||||
|
||||
**उन तथ्यों का पता लगाएं जिन्हें गलत माना गया था:**
|
||||
```
|
||||
S: ? # कोई भी उद्धृत ट्रिपल
|
||||
P: <discoveredFalseOn>
|
||||
O: ? # कोई भी मान (अस्तित्व)
|
||||
```
|
||||
|
||||
#### उत्पत्ति क्वेरी
|
||||
|
||||
**किसी विशिष्ट स्रोत द्वारा समर्थित सभी तथ्यों का पता लगाएं:**
|
||||
```
|
||||
S: ? # कोई भी उद्धृत ट्रिपल
|
||||
P: <supportedBy>
|
||||
O: <source:document-123>
|
||||
```
|
||||
|
||||
**पता करें कि कौन से स्रोत किसी विशिष्ट तथ्य का समर्थन करते हैं:**
|
||||
```
|
||||
S: << <ड्रगए> <उपचार करता है> <बीमारीबी> >> # विषय के रूप में उद्धृत ट्रिपल
|
||||
P: <supportedBy>
|
||||
O: ? # स्रोत IRI लौटाता है
|
||||
```
|
||||
|
||||
#### सत्यता क्वेरी
|
||||
|
||||
**उन दावों का पता लगाएं जिन्हें किसी व्यक्ति ने सत्य के रूप में चिह्नित किया था:**
|
||||
```
|
||||
S: ? # कोई भी उद्धृत ट्रिपल
|
||||
P: <assertedTrueBy>
|
||||
O: <person:Alice>
|
||||
```
|
||||
|
||||
**विरोधाभासी दावों का पता लगाएं (एक ही तथ्य, अलग-अलग सत्यता):**
|
||||
```
|
||||
# पहली क्वेरी: सत्य माने गए तथ्य
|
||||
S: ?
|
||||
P: <assertedTrueBy>
|
||||
O: ?
|
||||
|
||||
# दूसरी क्वेरी: झूठे माने गए तथ्य
|
||||
S: ?
|
||||
P: <assertedFalseBy>
|
||||
O: ?
|
||||
|
||||
# एप्लिकेशन तर्क: विषयों के चौराहे का पता लगाएं
|
||||
```
|
||||
|
||||
**उस विश्वास स्कोर का पता लगाएं जो थ्रेसहोल्ड से नीचे है:**
|
||||
```
|
||||
S: ? # कोई भी उद्धृत ट्रिपल
|
||||
P: <trustScore>
|
||||
O: < 0.5 # संख्यात्मक तुलना
|
||||
```
|
||||
|
||||
### आर्किटेक्चर
|
||||
|
||||
कई घटकों में महत्वपूर्ण परिवर्तन आवश्यक हैं:
|
||||
|
||||
#### यह भंडार (trustgraph)
|
||||
|
||||
- **स्कीमा प्रिमिटिव** (`trustgraph-base/trustgraph/schema/core/primitives.py`)
|
||||
- वैल्यू → टर्म का नाम बदलें
|
||||
- नए टर्म संरचना में प्रकार विभेदक
|
||||
- ग्राफ संदर्भ के लिए ट्रिपल में `g`
|
||||
- **नाम बदलें**: `Value` क्लास का नाम बदलकर `Term` कर दिया जाएगा। यह
|
||||
~78 फ़ाइलों को कोडबेस में प्रभावित करता है। नामकरण एक मजबूर करने वाला कारक के रूप में कार्य करता है:
|
||||
`Value` का उपयोग करने वाला कोई भी कोड तुरंत पहचानने योग्य है और इसे 2.0
|
||||
संगतता के लिए समीक्षा/अपडेट करने की आवश्यकता है।
|
||||
|
||||
सुरक्षा विचार
|
||||
नामित ग्राफ एक सुरक्षा सुविधा नहीं हैं। उपयोगकर्ता और संग्रह सुरक्षा सीमाएँ हैं।
|
||||
नामित ग्राफ डेटा संगठन और पुन:पुनर्बलन समर्थन के लिए पूरी तरह से हैं।
|
||||
|
||||
प्रदर्शन विचार
|
||||
- उद्धृत ट्रिपल नेस्टिंग गहराई जोड़ते हैं - यह क्वेरी प्रदर्शन को प्रभावित कर सकता है
|
||||
- कुशल ग्राफ-स्कोप वाली क्वेरी के लिए नामित ग्राफ इंडेक्सिंग रणनीतियाँ आवश्यक हैं
|
||||
- क्वाड स्टोरेज को कुशलतापूर्वक समायोजित करने के लिए Cassandra स्कीमा डिज़ाइन
|
||||
आवश्यक होगा।
|
||||
|
||||
वेक्टर स्टोर सीमा
|
||||
वेक्टर स्टोर हमेशा केवल IRIs को संदर्भित करते हैं:
|
||||
- कभी भी किनारे (उद्धृत ट्रिपल)
|
||||
- कभी भी शाब्दिक मान
|
||||
- कभी भी रिक्त नोड
|
||||
यह वेक्टर स्टोर को सरल रखता है - यह नामित संस्थाओं की सिमेंटिक समानता को संभालता है।
|
||||
ग्राफ संरचना, पुन:पुनर्बलन और मेटाडेटा संबंध को संभालता है। उद्धृत ट्रिपल और
|
||||
नामित ग्राफ वेक्टर संचालन को जटिल नहीं बनाते हैं।
|
||||
|
||||
परीक्षण रणनीति
|
||||
मौजूदा परीक्षण रणनीति का उपयोग करें। चूंकि यह एक ब्रेकिंग रिलीज़ है, इसलिए नए
|
||||
संरचनाओं का परीक्षण करने के लिए एंड-टू-एंड परीक्षण सूट पर ध्यान केंद्रित करें ताकि यह सत्यापित किया जा सके कि
|
||||
वे सभी घटकों में सही ढंग से काम करते हैं।
|
||||
|
||||
प्रवासन योजना
|
||||
- 2.0 एक ब्रेकिंग रिलीज़ है; कोई पिछड़ा संगतता की आवश्यकता नहीं है
|
||||
- मौजूदा डेटा को नए स्कीमा में माइग्रेट करने की आवश्यकता हो सकती है (अंतिम डिज़ाइन के आधार पर TBD)
|
||||
- मौजूदा ट्रिपल को बदलने के लिए माइग्रेशन टूल पर विचार करें
|
||||
|
||||
खुले प्रश्न
|
||||
- **रिक्त नोड**: सीमित समर्थन की पुष्टि की गई है। एक स्कोलेम रणनीति पर निर्णय लेने
|
||||
हो सकता है (लोडिंग पर IRI उत्पन्न करें, या रिक्त नोड ID को संरक्षित करें)।
|
||||
- **क्वेरी सिंटैक्स**: उद्धृत ट्रिपल को क्वेरी में निर्दिष्ट करने के लिए ठोस सिंटैक्स क्या है?
|
||||
क्वेरी API को परिभाषित करने की आवश्यकता है।
|
||||
- ~~**विधेय शब्दावली**~~: हल किया गया। किसी भी वैध RDF विधेय की अनुमति है,
|
||||
जिसमें कस्टम उपयोगकर्ता-परिभाषित भी शामिल हैं। RDF वैधता के बारे में बहुत कम धारणाएं।
|
||||
रणनीति: जब तक बिल्कुल आवश्यक न हो, कुछ भी लॉक न करें।
|
||||
- ~~**वेक्टर स्टोर प्रभाव**~~: हल किया गया। वेक्टर स्टोर हमेशा केवल IRIs को संदर्भित करते हैं
|
||||
- कभी भी किनारे, शाब्दिक, या रिक्त नोड। उद्धृत ट्रिपल और
|
||||
पुन:पुनर्बलन वेक्टर स्टोर को प्रभावित नहीं करते हैं।
|
||||
- ~~**नामित ग्राफ अर्थशास्त्र**~~: हल किया गया। क्वेरी डिफ़ॉल्ट में डिफ़ॉल्ट ग्राफ
|
||||
(पिछड़ी संगत SPARQL व्यवहार)। नामित ग्राफ या सभी ग्राफों को क्वेरी करने के लिए
|
||||
एक स्पष्ट ग्राफ पैरामीटर की आवश्यकता होती है।
|
||||
|
||||
संदर्भ
|
||||
- [RDF 1.2 अवधारणाएँ](https://www.w3.org/TR/rdf12-concepts/)
|
||||
- [RDF-स्टार और SPARQL-स्टार](https://w3c.github.io/rdf-star/)
|
||||
- [RDF डेटासेट](https://www.w3.org/TR/rdf11-concepts/#section-dataset)
|
||||
533
docs/tech-specs/hi/graphql-query.hi.md
Normal file
533
docs/tech-specs/hi/graphql-query.hi.md
Normal file
|
|
@ -0,0 +1,533 @@
|
|||
---
|
||||
layout: default
|
||||
title: "GraphQL क्वेरी तकनीकी विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# GraphQL क्वेरी तकनीकी विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह विनिर्देश अपाचे कैसेंड्रा में ट्रस्टग्राफ के संरचित डेटा भंडारण के लिए एक GraphQL क्वेरी इंटरफ़ेस के कार्यान्वयन का वर्णन करता है। संरचित-डेटा.md विनिर्देश में उल्लिखित संरचित डेटा क्षमताओं पर निर्माण करते हुए, यह दस्तावेज़ बताता है कि निकाले गए और संसाधित संरचित ऑब्जेक्ट युक्त कैसेंड्रा तालिकाओं के खिलाफ GraphQL क्वेरी कैसे निष्पादित की जाएंगी।
|
||||
|
||||
<<<<<<< HEAD
|
||||
GraphQL क्वेरी सेवा कैसेंड्रा में संग्रहीत संरचित डेटा के लिए एक लचीला, टाइप-सुरक्षित इंटरफ़ेस प्रदान करेगी। यह स्कीमा परिवर्तनों के लिए गतिशील रूप से अनुकूल होगा, ऑब्जेक्ट के बीच संबंधों सहित जटिल प्रश्नों का समर्थन करेगा, और ट्रस्टग्राफ के मौजूदा संदेश-आधारित वास्तुकला के साथ सहजता से एकीकृत होगा।
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
**गतिशील स्कीमा समर्थन**: सेवा को पुनरारंभ किए बिना कॉन्फ़िगरेशन में स्कीमा परिवर्तनों के लिए स्वचालित रूप से अनुकूल होना।
|
||||
=======
|
||||
GraphQL क्वेरी सेवा कैसेंड्रा में संग्रहीत संरचित डेटा के लिए एक लचीला, टाइप-सुरक्षित इंटरफ़ेस प्रदान करेगी। यह स्कीमा परिवर्तनों के लिए गतिशील रूप से अनुकूल होगा, ऑब्जेक्ट के बीच संबंधों सहित जटिल क्वेरी का समर्थन करेगा, और ट्रस्टग्राफ के मौजूदा संदेश-आधारित आर्किटेक्चर के साथ सहजता से एकीकृत होगा।
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
**डायनामिक स्कीमा समर्थन**: सेवा को पुनरारंभ किए बिना कॉन्फ़िगरेशन में स्कीमा परिवर्तनों के लिए स्वचालित रूप से अनुकूल होना।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**GraphQL मानकों का अनुपालन**: मौजूदा GraphQL टूलिंग और क्लाइंट के साथ संगत एक मानक GraphQL इंटरफ़ेस प्रदान करना।
|
||||
**कुशल कैसेंड्रा क्वेरी**: GraphQL क्वेरी को कुशल कैसेंड्रा CQL क्वेरी में अनुवाद करना, विभाजन कुंजियों और अनुक्रमणिकाओं का सम्मान करना।
|
||||
**संबंध संकल्प**: विभिन्न ऑब्जेक्ट प्रकारों के बीच संबंधों के लिए GraphQL फ़ील्ड रिज़ॉल्वर का समर्थन करना।
|
||||
**टाइप सुरक्षा**: स्कीमा परिभाषाओं के आधार पर टाइप-सुरक्षित क्वेरी निष्पादन और प्रतिक्रिया पीढ़ी सुनिश्चित करना।
|
||||
<<<<<<< HEAD
|
||||
**मापनीय प्रदर्शन**: उचित कनेक्शन पूलिंग और क्वेरी अनुकूलन के साथ समवर्ती प्रश्नों को कुशलतापूर्वक संभालना।
|
||||
=======
|
||||
**स्केलेबल प्रदर्शन**: उचित कनेक्शन पूलिंग और क्वेरी अनुकूलन के साथ समवर्ती क्वेरी को कुशलतापूर्वक संभालना।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**अनुरोध/प्रतिक्रिया एकीकरण**: ट्रस्टग्राफ के पल्सर-आधारित अनुरोध/प्रतिक्रिया पैटर्न के साथ संगतता बनाए रखना।
|
||||
**त्रुटि प्रबंधन**: स्कीमा मिसमैच, क्वेरी त्रुटियों और डेटा सत्यापन मुद्दों के लिए व्यापक त्रुटि रिपोर्टिंग प्रदान करना।
|
||||
|
||||
## पृष्ठभूमि
|
||||
|
||||
<<<<<<< HEAD
|
||||
संरचित डेटा भंडारण कार्यान्वयन (trustgraph-flow/trustgraph/storage/objects/cassandra/) ट्रस्टग्राफ के कॉन्फ़िगरेशन सिस्टम में संग्रहीत स्कीमा परिभाषाओं के आधार पर कैसेंड्रा तालिकाओं में ऑब्जेक्ट लिखता है। ये तालिकाएँ एक समग्र विभाजन कुंजी संरचना का उपयोग करती हैं जिसमें संग्रह और स्कीमा-परिभाषित प्राथमिक कुंजियाँ होती हैं, जो संग्रह के भीतर कुशल प्रश्नों को सक्षम करती हैं।
|
||||
=======
|
||||
संरचित डेटा भंडारण कार्यान्वयन (trustgraph-flow/trustgraph/storage/objects/cassandra/) ट्रस्टग्राफ के कॉन्फ़िगरेशन सिस्टम में संग्रहीत स्कीमा परिभाषाओं के आधार पर कैसेंड्रा तालिकाओं में ऑब्जेक्ट लिखता है। ये तालिकाएँ एक समग्र विभाजन कुंजी संरचना का उपयोग करती हैं जिसमें संग्रह और स्कीमा-परिभाषित प्राथमिक कुंजियाँ होती हैं, जो संग्रह के भीतर कुशल क्वेरी को सक्षम करती हैं।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
वर्तमान सीमाएँ जिन्हें इस विनिर्देश द्वारा संबोधित किया गया है:
|
||||
कैसेंड्रा में संग्रहीत संरचित डेटा के लिए कोई क्वेरी इंटरफ़ेस नहीं।
|
||||
संरचित डेटा के लिए GraphQL की शक्तिशाली क्वेरी क्षमताओं का लाभ उठाने में असमर्थता।
|
||||
संबंधित ऑब्जेक्ट के बीच संबंध ट्रैवर्सल के लिए कोई समर्थन नहीं।
|
||||
<<<<<<< HEAD
|
||||
संरचित डेटा एक्सेस के लिए एक मानकीकृत क्वेरी भाषा का अभाव।
|
||||
=======
|
||||
संरचित डेटा एक्सेस के लिए एक मानकीकृत क्वेरी भाषा की कमी।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
GraphQL क्वेरी सेवा इन कमियों को भरकर:
|
||||
कैसेंड्रा तालिकाओं के लिए एक मानक GraphQL इंटरफ़ेस प्रदान करना।
|
||||
ट्रस्टग्राफ कॉन्फ़िगरेशन से गतिशील रूप से GraphQL स्कीमा उत्पन्न करना।
|
||||
कुशलतापूर्वक GraphQL क्वेरी को कैसेंड्रा CQL में अनुवाद करना।
|
||||
फ़ील्ड रिज़ॉल्वर के माध्यम से संबंध संकल्प का समर्थन करना।
|
||||
|
||||
## तकनीकी डिजाइन
|
||||
|
||||
<<<<<<< HEAD
|
||||
### वास्तुकला
|
||||
=======
|
||||
### आर्किटेक्चर
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
GraphQL क्वेरी सेवा को एक नए ट्रस्टग्राफ फ्लो प्रोसेसर के रूप में लागू किया जाएगा जो स्थापित पैटर्न का पालन करता है:
|
||||
|
||||
**मॉड्यूल स्थान**: `trustgraph-flow/trustgraph/query/objects/cassandra/`
|
||||
|
||||
**मुख्य घटक**:
|
||||
|
||||
1. **GraphQL क्वेरी सेवा प्रोसेसर**
|
||||
बेस FlowProcessor क्लास का विस्तार करता है।
|
||||
मौजूदा क्वेरी सेवाओं के समान अनुरोध/प्रतिक्रिया पैटर्न को लागू करता है।
|
||||
स्कीमा अपडेट के लिए कॉन्फ़िगरेशन की निगरानी करता है।
|
||||
कॉन्फ़िगरेशन के साथ GraphQL स्कीमा को सिंक्रनाइज़ रखता है।
|
||||
|
||||
<<<<<<< HEAD
|
||||
2. **गतिशील स्कीमा जनरेटर**
|
||||
=======
|
||||
2. **डायनामिक स्कीमा जनरेटर**
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
ट्रस्टग्राफ RowSchema परिभाषाओं को GraphQL प्रकारों में परिवर्तित करता है।
|
||||
उचित फ़ील्ड परिभाषाओं के साथ GraphQL ऑब्जेक्ट प्रकार बनाता है।
|
||||
संग्रह-आधारित रिज़ॉल्वर के साथ रूट क्वेरी प्रकार उत्पन्न करता है।
|
||||
जब कॉन्फ़िगरेशन बदलता है तो GraphQL स्कीमा को अपडेट करता है।
|
||||
|
||||
3. **क्वेरी निष्पादक**
|
||||
Strawberry लाइब्रेरी का उपयोग करके आने वाली GraphQL क्वेरी को पार्स करता है।
|
||||
वर्तमान स्कीमा के विरुद्ध क्वेरी को मान्य करता है।
|
||||
क्वेरी निष्पादित करता है और संरचित प्रतिक्रियाएँ लौटाता है।
|
||||
<<<<<<< HEAD
|
||||
विस्तृत त्रुटि संदेशों के साथ त्रुटियों को कुशलतापूर्वक संभालता है।
|
||||
|
||||
4. **कैसेंड्रा क्वेरी अनुवादक**
|
||||
=======
|
||||
विस्तृत त्रुटि संदेशों के साथ त्रुटियों को सुचारू रूप से संभालता है।
|
||||
|
||||
4. **कैसेंड्रा क्वेरी ट्रांसलेटर**
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
GraphQL चयन को CQL क्वेरी में परिवर्तित करता है।
|
||||
उपलब्ध अनुक्रमणिकाओं और विभाजन कुंजियों के आधार पर क्वेरी को अनुकूलित करता है।
|
||||
फ़िल्टरिंग, पेजिंग और सॉर्टिंग को संभालता है।
|
||||
कनेक्शन पूलिंग और सत्र जीवनचक्र का प्रबंधन करता है।
|
||||
|
||||
5. **संबंध रिज़ॉल्वर**
|
||||
ऑब्जेक्ट संबंधों के लिए फ़ील्ड रिज़ॉल्वर को लागू करता है।
|
||||
N+1 क्वेरी से बचने के लिए कुशल बैच लोडिंग करता है।
|
||||
अनुरोध संदर्भ के भीतर हल किए गए संबंधों को कैश करता है।
|
||||
आगे और पीछे दोनों संबंध ट्रैवर्सल का समर्थन करता है।
|
||||
|
||||
### कॉन्फ़िगरेशन स्कीमा निगरानी
|
||||
|
||||
सेवा स्कीमा अपडेट प्राप्त करने के लिए एक कॉन्फ़िगरेशन हैंडलर को पंजीकृत करेगी:
|
||||
|
||||
```python
|
||||
self.register_config_handler(self.on_schema_config)
|
||||
```
|
||||
|
||||
जब स्कीमा बदलते हैं:
|
||||
1. कॉन्फ़िगरेशन से नए स्कीमा परिभाषाओं को पार्स करें।
|
||||
2. GraphQL प्रकारों और रिज़ॉल्वरों को फिर से उत्पन्न करें।
|
||||
3. निष्पादन योग्य स्कीमा को अपडेट करें।
|
||||
4. किसी भी स्कीमा-निर्भर कैश को साफ़ करें।
|
||||
|
||||
### GraphQL स्कीमा पीढ़ी
|
||||
|
||||
कॉन्फ़िगरेशन में प्रत्येक RowSchema के लिए, निम्नलिखित उत्पन्न करें:
|
||||
|
||||
1. **GraphQL ऑब्जेक्ट टाइप**:
|
||||
फ़ील्ड प्रकारों को मैप करें (string → String, integer → Int, float → Float, boolean → Boolean)।
|
||||
आवश्यक फ़ील्ड को GraphQL में गैर-शून्य के रूप में चिह्नित करें।
|
||||
स्कीमा से फ़ील्ड विवरण जोड़ें।
|
||||
|
||||
2. **रूट क्वेरी फ़ील्ड**:
|
||||
संग्रह क्वेरी (जैसे, `customers`, `transactions`)।
|
||||
अनुक्रमित फ़ील्ड के आधार पर फ़िल्टरिंग तर्क।
|
||||
पेजिंग समर्थन (सीमा, ऑफ़सेट)।
|
||||
सॉर्ट करने योग्य फ़ील्ड के लिए सॉर्टिंग विकल्प।
|
||||
|
||||
3. **रिलेशनशिप फ़ील्ड**:
|
||||
स्कीमा से विदेशी कुंजी संबंधों की पहचान करें।
|
||||
संबंधित ऑब्जेक्ट के लिए फ़ील्ड रिज़ॉल्वर बनाएं।
|
||||
एकल ऑब्जेक्ट और सूची दोनों संबंधों का समर्थन करें।
|
||||
|
||||
### क्वेरी निष्पादन प्रवाह
|
||||
|
||||
<<<<<<< HEAD
|
||||
1. **अनुरोध स्वागत**:
|
||||
=======
|
||||
1. **अनुरोध रिसेप्शन**:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Pulsar से ObjectsQueryRequest प्राप्त करें।
|
||||
GraphQL क्वेरी स्ट्रिंग और चर निकालें।
|
||||
उपयोगकर्ता और संग्रह संदर्भ की पहचान करें।
|
||||
|
||||
2. **क्वेरी सत्यापन**:
|
||||
Strawberry का उपयोग करके GraphQL क्वेरी को पार्स करें।
|
||||
वर्तमान स्कीमा के विरुद्ध मान्य करें।
|
||||
फ़ील्ड चयन और तर्क प्रकारों की जांच करें।
|
||||
|
||||
3. **CQL पीढ़ी**:
|
||||
GraphQL चयन का विश्लेषण करें।
|
||||
उचित WHERE खंडों के साथ CQL क्वेरी बनाएं।
|
||||
विभाजन कुंजी में संग्रह शामिल करें।
|
||||
GraphQL तर्कों के आधार पर फ़िल्टर लागू करें।
|
||||
|
||||
4. **क्वेरी निष्पादन**:
|
||||
Cassandra के खिलाफ CQL क्वेरी निष्पादित करें।
|
||||
परिणामों को GraphQL प्रतिक्रिया संरचना में मैप करें।
|
||||
किसी भी रिलेशनशिप फ़ील्ड को हल करें।
|
||||
GraphQL विनिर्देश के अनुसार प्रतिक्रिया को प्रारूपित करें।
|
||||
|
||||
5. **प्रतिक्रिया वितरण**:
|
||||
परिणामों के साथ ObjectsQueryResponse बनाएं।
|
||||
किसी भी निष्पादन त्रुटि को शामिल करें।
|
||||
सहसंबंध आईडी के साथ Pulsar के माध्यम से प्रतिक्रिया भेजें।
|
||||
|
||||
### डेटा मॉडल
|
||||
|
||||
> **ध्यान दें**: `trustgraph-base/trustgraph/schema/services/structured_query.py` में एक मौजूदा StructuredQueryRequest/Response स्कीमा मौजूद है। हालाँकि, इसमें महत्वपूर्ण फ़ील्ड (उपयोगकर्ता, संग्रह) की कमी है और यह उप-इष्टतम प्रकारों का उपयोग करता है। नीचे दिए गए स्कीमा अनुशंसित विकास का प्रतिनिधित्व करते हैं, जिसे या तो मौजूदा स्कीमा को बदलने के लिए या नए ObjectsQueryRequest/Response प्रकारों के रूप में बनाया जाना चाहिए।
|
||||
|
||||
#### अनुरोध स्कीमा (ObjectsQueryRequest)
|
||||
|
||||
```python
|
||||
from pulsar.schema import Record, String, Map, Array
|
||||
|
||||
class ObjectsQueryRequest(Record):
|
||||
user = String() # Cassandra keyspace (follows pattern from TriplesQueryRequest)
|
||||
collection = String() # Data collection identifier (required for partition key)
|
||||
query = String() # GraphQL query string
|
||||
variables = Map(String()) # GraphQL variables (consider enhancing to support all JSON types)
|
||||
operation_name = String() # Operation to execute for multi-operation documents
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
**मौजूदा StructuredQueryRequest से परिवर्तनों का तर्क:**
|
||||
=======
|
||||
**मौजूदा StructuredQueryRequest से परिवर्तनों का कारण:**
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
अन्य क्वेरी सेवाओं के पैटर्न से मेल खाने के लिए `user` और `collection` फ़ील्ड जोड़े गए।
|
||||
ये फ़ील्ड कैसेंड्रा की स्पेस और कलेक्शन की पहचान करने के लिए आवश्यक हैं।
|
||||
वेरिएबल अभी भी Map(String()) के रूप में हैं, लेकिन आदर्श रूप से सभी JSON प्रकारों का समर्थन करना चाहिए।
|
||||
|
||||
#### प्रतिक्रिया स्कीमा (ObjectsQueryResponse)
|
||||
|
||||
```python
|
||||
from pulsar.schema import Record, String, Array
|
||||
from ..core.primitives import Error
|
||||
|
||||
class GraphQLError(Record):
|
||||
message = String()
|
||||
path = Array(String()) # Path to the field that caused the error
|
||||
extensions = Map(String()) # Additional error metadata
|
||||
|
||||
class ObjectsQueryResponse(Record):
|
||||
error = Error() # System-level error (connection, timeout, etc.)
|
||||
data = String() # JSON-encoded GraphQL response data
|
||||
errors = Array(GraphQLError) # GraphQL field-level errors
|
||||
extensions = Map(String()) # Query metadata (execution time, etc.)
|
||||
```
|
||||
|
||||
**मौजूदा StructuredQueryResponse से परिवर्तनों का कारण:**
|
||||
सिस्टम त्रुटियों (`error`) और GraphQL त्रुटियों (`errors`) के बीच अंतर करता है।
|
||||
स्ट्रिंग सरणी के बजाय संरचित GraphQLError ऑब्जेक्ट का उपयोग करता है।
|
||||
GraphQL विनिर्देश के अनुपालन के लिए `extensions` फ़ील्ड जोड़ता है।
|
||||
अनुकूलता के लिए डेटा को JSON स्ट्रिंग के रूप में रखता है, हालांकि मूल प्रकार बेहतर होंगे।
|
||||
|
||||
### कैसेंड्रा क्वेरी अनुकूलन
|
||||
|
||||
सेवा कैसेंड्रा क्वेरी को इस प्रकार अनुकूलित करेगी:
|
||||
|
||||
1. **पार्टिशन कुंजियों का सम्मान करना:**
|
||||
हमेशा क्वेरी में संग्रह शामिल करें।
|
||||
स्कीमा-परिभाषित प्राथमिक कुंजियों का कुशलतापूर्वक उपयोग करें।
|
||||
पूर्ण तालिका स्कैन से बचें।
|
||||
|
||||
2. **सूचकांकों का उपयोग करना:**
|
||||
फ़िल्टरिंग के लिए द्वितीयक सूचकांकों का उपयोग करें।
|
||||
जब संभव हो, तो कई फ़िल्टरों को मिलाएं।
|
||||
चेतावनी दें जब क्वेरी अक्षम हो सकती हैं।
|
||||
|
||||
3. **बैच लोडिंग:**
|
||||
संबंध क्वेरी एकत्र करें।
|
||||
राउंड ट्रिप को कम करने के लिए बैचों में निष्पादित करें।
|
||||
अनुरोध संदर्भ के भीतर परिणामों को कैश करें।
|
||||
|
||||
4. **कनेक्शन प्रबंधन:**
|
||||
लगातार कैसेंड्रा सत्र बनाए रखें।
|
||||
कनेक्शन पूलिंग का उपयोग करें।
|
||||
विफलताओं पर पुनः कनेक्शन को संभालें।
|
||||
|
||||
### उदाहरण GraphQL क्वेरी
|
||||
|
||||
#### सरल संग्रह क्वेरी
|
||||
```graphql
|
||||
{
|
||||
customers(status: "active") {
|
||||
customer_id
|
||||
name
|
||||
email
|
||||
registration_date
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### संबंधों के साथ प्रश्न
|
||||
```graphql
|
||||
{
|
||||
orders(order_date_gt: "2024-01-01") {
|
||||
order_id
|
||||
total_amount
|
||||
customer {
|
||||
name
|
||||
email
|
||||
}
|
||||
items {
|
||||
product_name
|
||||
quantity
|
||||
price
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### पृष्ठों में विभाजित क्वेरी
|
||||
```graphql
|
||||
{
|
||||
products(limit: 20, offset: 40) {
|
||||
product_id
|
||||
name
|
||||
price
|
||||
category
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### कार्यान्वयन निर्भरताएँ
|
||||
|
||||
<<<<<<< HEAD
|
||||
**स्ट्रॉबेरी ग्राफक्यूएल (Strawberry GraphQL)**: ग्राफक्यूएल स्कीमा परिभाषा और क्वेरी निष्पादन के लिए
|
||||
**कैसेंड्रा ड्राइवर (Cassandra Driver)**: डेटाबेस कनेक्टिविटी के लिए (भंडारण मॉड्यूल में पहले से उपयोग किया गया)
|
||||
**ट्रस्टग्राफ बेस (TrustGraph Base)**: फ्लोप्रोसेसर और स्कीमा परिभाषाओं के लिए
|
||||
**कॉन्फ़िगरेशन सिस्टम (Configuration System)**: स्कीमा निगरानी और अपडेट के लिए
|
||||
=======
|
||||
**स्ट्रॉबेरी ग्राफक्यूएल**: ग्राफक्यूएल स्कीमा परिभाषा और क्वेरी निष्पादन के लिए
|
||||
**कैसेंड्रा ड्राइवर**: डेटाबेस कनेक्टिविटी के लिए (भंडारण मॉड्यूल में पहले से उपयोग किया गया)
|
||||
**ट्रस्टग्राफ बेस**: फ्लोप्रोसेसर और स्कीमा परिभाषाओं के लिए
|
||||
**कॉन्फ़िगरेशन सिस्टम**: स्कीमा निगरानी और अपडेट के लिए
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
### कमांड-लाइन इंटरफ़ेस
|
||||
|
||||
सेवा एक CLI कमांड प्रदान करेगी: `kg-query-objects-graphql-cassandra`
|
||||
|
||||
तर्क:
|
||||
`--cassandra-host`: कैसेंड्रा क्लस्टर संपर्क बिंदु
|
||||
`--cassandra-username`: प्रमाणीकरण उपयोगकर्ता नाम
|
||||
`--cassandra-password`: प्रमाणीकरण पासवर्ड
|
||||
`--config-type`: स्कीमा के लिए कॉन्फ़िगरेशन प्रकार (डिफ़ॉल्ट: "स्कीमा")
|
||||
मानक फ्लोप्रोसेसर तर्क (पल्सर कॉन्फ़िगरेशन, आदि)
|
||||
|
||||
## एपीआई एकीकरण
|
||||
|
||||
<<<<<<< HEAD
|
||||
### पल्सर विषय (Pulsar Topics)
|
||||
|
||||
**इनपुट टॉपिक (Input Topic)**: `objects-graphql-query-request`
|
||||
स्कीमा: ऑब्जेक्ट्सक्वेरीरिक्वेस्ट (ObjectsQueryRequest)
|
||||
गेटवे सेवाओं से ग्राफक्यूएल क्वेरी प्राप्त करता है
|
||||
|
||||
**आउटपुट टॉपिक (Output Topic)**: `objects-graphql-query-response`
|
||||
स्कीमा: ऑब्जेक्ट्सक्वेरीरिस्पांस (ObjectsQueryResponse)
|
||||
=======
|
||||
### पल्सर विषय
|
||||
|
||||
**इनपुट टॉपिक**: `objects-graphql-query-request`
|
||||
स्कीमा: ऑब्जेक्ट्सक्वेरीरिक्वेस्ट
|
||||
गेटवे सेवाओं से ग्राफक्यूएल क्वेरी प्राप्त करता है
|
||||
|
||||
**आउटपुट टॉपिक**: `objects-graphql-query-response`
|
||||
स्कीमा: ऑब्जेक्ट्सक्वेरीरिस्पांस
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
क्वेरी परिणाम और त्रुटियां लौटाता है
|
||||
|
||||
### गेटवे एकीकरण
|
||||
|
||||
गेटवे और रिवर्स-गेटवे को निम्नलिखित के लिए एंडपॉइंट की आवश्यकता होगी:
|
||||
1. क्लाइंट से ग्राफक्यूएल क्वेरी स्वीकार करें
|
||||
<<<<<<< HEAD
|
||||
2. पल्सर के माध्यम से क्वेरी सेवा को आगे बढ़ाएं
|
||||
3. क्लाइंट को प्रतिक्रियाएं लौटाएं
|
||||
=======
|
||||
2. पल्सर के माध्यम से क्वेरी सेवा को भेजें
|
||||
3. क्लाइंट को प्रतिक्रिया लौटाएं
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
4. ग्राफक्यूएल इंट्रॉस्पेक्शन क्वेरी का समर्थन करें
|
||||
|
||||
### एजेंट टूल एकीकरण
|
||||
|
||||
<<<<<<< HEAD
|
||||
एक नया एजेंट टूल क्लास निम्नलिखित को सक्षम करेगा:
|
||||
=======
|
||||
एक नई एजेंट टूल क्लास निम्नलिखित को सक्षम करेगी:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
प्राकृतिक भाषा से ग्राफक्यूएल क्वेरी पीढ़ी
|
||||
प्रत्यक्ष ग्राफक्यूएल क्वेरी निष्पादन
|
||||
परिणाम व्याख्या और स्वरूपण
|
||||
एजेंट निर्णय प्रवाह के साथ एकीकरण
|
||||
|
||||
## सुरक्षा विचार
|
||||
|
||||
<<<<<<< HEAD
|
||||
**क्वेरी गहराई सीमित करना (Query Depth Limiting)**: गहराई से नेस्टेड क्वेरी को रोकें जो प्रदर्शन समस्याओं का कारण बन सकती हैं
|
||||
**क्वेरी जटिलता विश्लेषण (Query Complexity Analysis)**: संसाधन समाप्त होने से रोकने के लिए क्वेरी जटिलता को सीमित करें
|
||||
**फ़ील्ड-लेवल अनुमतियाँ (Field-Level Permissions)**: उपयोगकर्ता भूमिकाओं के आधार पर फ़ील्ड-लेवल एक्सेस नियंत्रण के लिए भविष्य का समर्थन
|
||||
**इनपुट सैनिटाइजेशन (Input Sanitization)**: इंजेक्शन हमलों को रोकने के लिए सभी क्वेरी इनपुट को मान्य और सैनिटाइज करें
|
||||
**दर सीमित करना (Rate Limiting)**: प्रति उपयोगकर्ता/संग्रहण क्वेरी दर सीमित करना लागू करें
|
||||
|
||||
## प्रदर्शन विचार
|
||||
|
||||
**क्वेरी योजना (Query Planning)**: सीक्यूएल पीढ़ी को अनुकूलित करने के लिए निष्पादन से पहले क्वेरी का विश्लेषण करें
|
||||
**परिणाम कैशिंग (Result Caching)**: फ़ील्ड रिज़ॉल्वर स्तर पर बार-बार एक्सेस किए जाने वाले डेटा को कैश करने पर विचार करें
|
||||
**कनेक्शन पूलिंग (Connection Pooling)**: कैसेंड्रा के लिए कुशल कनेक्शन पूल बनाए रखें
|
||||
**बैच ऑपरेशन (Batch Operations)**: जब भी संभव हो, कई क्वेरी को संयोजित करें ताकि विलंबता कम हो सके
|
||||
**निगरानी (Monitoring)**: अनुकूलन के लिए क्वेरी प्रदर्शन मेट्रिक्स को ट्रैक करें
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
### यूनिट परीक्षण
|
||||
रोस्कीमा परिभाषाओं से स्कीमा पीढ़ी
|
||||
ग्राफक्यूएल क्वेरी पार्सिंग और सत्यापन
|
||||
सीक्यूएल क्वेरी पीढ़ी तर्क
|
||||
=======
|
||||
**क्वेरी गहराई सीमित करना**: ऐसे गहराई से नेस्टेड क्वेरी को रोकें जो प्रदर्शन समस्याओं का कारण बन सकते हैं
|
||||
**क्वेरी जटिलता विश्लेषण**: संसाधन समाप्त होने से रोकने के लिए क्वेरी जटिलता को सीमित करें
|
||||
**फ़ील्ड-स्तरीय अनुमतियाँ**: भविष्य में उपयोगकर्ता भूमिकाओं के आधार पर फ़ील्ड-स्तरीय एक्सेस नियंत्रण के लिए समर्थन
|
||||
**इनपुट सैनिटाइजेशन**: इंजेक्शन हमलों को रोकने के लिए सभी क्वेरी इनपुट को मान्य और सैनिटाइज करें
|
||||
**दर सीमित करना**: प्रति उपयोगकर्ता/संग्रहण क्वेरी दर सीमित करना लागू करें
|
||||
|
||||
## प्रदर्शन विचार
|
||||
|
||||
**क्वेरी योजना**: CQL पीढ़ी को अनुकूलित करने के लिए निष्पादन से पहले क्वेरी का विश्लेषण करें
|
||||
**परिणाम कैशिंग**: फ़ील्ड रिज़ॉल्वर स्तर पर बार-बार एक्सेस किए जाने वाले डेटा को कैश करने पर विचार करें
|
||||
**कनेक्शन पूलिंग**: कैसेंड्रा के लिए कुशल कनेक्शन पूल बनाए रखें
|
||||
**बैच ऑपरेशन**: जब भी संभव हो, कई क्वेरी को मिलाएं ताकि विलंबता कम हो सके
|
||||
**निगरानी**: अनुकूलन के लिए क्वेरी प्रदर्शन मेट्रिक्स को ट्रैक करें
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
### यूनिट टेस्ट
|
||||
RowSchema परिभाषाओं से स्कीमा पीढ़ी
|
||||
GraphQL क्वेरी पार्सिंग और सत्यापन
|
||||
CQL क्वेरी पीढ़ी लॉजिक
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
फ़ील्ड रिज़ॉल्वर कार्यान्वयन
|
||||
|
||||
### अनुबंध परीक्षण
|
||||
पल्सर संदेश अनुबंध अनुपालन
|
||||
<<<<<<< HEAD
|
||||
ग्राफक्यूएल स्कीमा वैधता
|
||||
=======
|
||||
GraphQL स्कीमा वैधता
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
प्रतिक्रिया प्रारूप सत्यापन
|
||||
त्रुटि संरचना सत्यापन
|
||||
|
||||
### एकीकरण परीक्षण
|
||||
<<<<<<< HEAD
|
||||
परीक्षण कैसेंड्रा उदाहरण के खिलाफ एंड-टू-एंड क्वेरी निष्पादन
|
||||
स्कीमा अपडेट हैंडलिंग
|
||||
संबंध संकल्प
|
||||
=======
|
||||
परीक्षण कैसेंड्रा इंस्टेंस के खिलाफ एंड-टू-एंड क्वेरी निष्पादन
|
||||
स्कीमा अपडेट हैंडलिंग
|
||||
संबंध समाधान
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
पेजिंग और फ़िल्टरिंग
|
||||
त्रुटि परिदृश्य
|
||||
|
||||
### प्रदर्शन परीक्षण
|
||||
लोड के तहत क्वेरी थ्रूपुट
|
||||
विभिन्न क्वेरी जटिलताओं के लिए प्रतिक्रिया समय
|
||||
बड़े परिणाम सेट के साथ मेमोरी उपयोग
|
||||
कनेक्शन पूल दक्षता
|
||||
|
||||
## माइग्रेशन योजना
|
||||
|
||||
<<<<<<< HEAD
|
||||
इस नई क्षमता के रूप में माइग्रेशन की आवश्यकता नहीं है। सेवा निम्नलिखित करेगी:
|
||||
1. कॉन्फ़िगरेशन से मौजूदा स्कीमा पढ़ें
|
||||
2. स्टोरेज मॉड्यूल द्वारा बनाए गए मौजूदा कैसेंड्रा तालिकाओं से कनेक्ट करें
|
||||
3. तैनाती पर तुरंत क्वेरी स्वीकार करना शुरू करें
|
||||
=======
|
||||
चूंकि यह एक नई क्षमता है, इसलिए माइग्रेशन की आवश्यकता नहीं है। सेवा निम्नलिखित कार्य करेगी:
|
||||
1. कॉन्फ़िगरेशन से मौजूदा स्कीमा पढ़ें
|
||||
2. स्टोरेज मॉड्यूल द्वारा बनाए गए मौजूदा कैसेंड्रा तालिकाओं से कनेक्ट करें
|
||||
3. परिनियोजन पर तुरंत क्वेरी स्वीकार करना शुरू करें
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## समयरेखा
|
||||
|
||||
सप्ताह 1-2: कोर सेवा कार्यान्वयन और स्कीमा पीढ़ी
|
||||
<<<<<<< HEAD
|
||||
सप्ताह 3: क्वेरी निष्पादन और सीक्यूएल अनुवाद
|
||||
सप्ताह 4: संबंध संकल्प और अनुकूलन
|
||||
सप्ताह 5: परीक्षण और प्रदर्शन ट्यूनिंग
|
||||
सप्ताह 6: गेटवे एकीकरण और प्रलेखन
|
||||
|
||||
## खुले प्रश्न
|
||||
|
||||
1. **स्कीमा विकास (Schema Evolution)**: सेवा स्कीमा संक्रमण के दौरान क्वेरी को कैसे संभालती है?
|
||||
विकल्प: स्कीमा अपडेट के दौरान क्वेरी को कतार में लगाएं
|
||||
विकल्प: एक साथ कई स्कीमा संस्करणों का समर्थन करें
|
||||
|
||||
2. **कैशिंग रणनीति (Caching Strategy)**: क्या क्वेरी परिणामों को कैश किया जाना चाहिए?
|
||||
विचार करें: समय-आधारित समाप्ति
|
||||
विचार करें: घटना-आधारित अमान्यकरण
|
||||
|
||||
3. **संघटन समर्थन (Federation Support)**: क्या सेवा अन्य डेटा स्रोतों के साथ संयोजन के लिए ग्राफक्यूएल संघटन का समर्थन करना चाहिए?
|
||||
यह संरचित और ग्राफ डेटा में एकीकृत क्वेरी को सक्षम करेगा
|
||||
|
||||
4. **सदस्यता समर्थन (Subscription Support)**: क्या सेवा वास्तविक समय अपडेट के लिए ग्राफक्यूएल सदस्यता का समर्थन करना चाहिए?
|
||||
|
||||
|
||||
5. **कस्टम स्केलर:** क्या डोमेन-विशिष्ट डेटा प्रकारों के लिए कस्टम स्केलर प्रकारों का समर्थन किया जाना चाहिए?
|
||||
=======
|
||||
सप्ताह 3: क्वेरी निष्पादन और CQL अनुवाद
|
||||
सप्ताह 4: संबंध समाधान और अनुकूलन
|
||||
सप्ताह 5: परीक्षण और प्रदर्शन ट्यूनिंग
|
||||
सप्ताह 6: गेटवे एकीकरण और दस्तावेज़ीकरण
|
||||
|
||||
## खुले प्रश्न
|
||||
|
||||
1. **स्कीमा विकास**: सेवा को स्कीमा संक्रमण के दौरान क्वेरी को कैसे संभालना चाहिए?
|
||||
विकल्प: स्कीमा अपडेट के दौरान क्वेरी को कतार में लगाएं
|
||||
विकल्प: एक साथ कई स्कीमा संस्करणों का समर्थन करें
|
||||
|
||||
2. **कैशिंग रणनीति**: क्या क्वेरी परिणामों को कैश किया जाना चाहिए?
|
||||
विचार करें: समय-आधारित समाप्ति
|
||||
विचार करें: घटना-आधारित अमान्यकरण
|
||||
|
||||
3. **संघटन समर्थन**: क्या सेवा को अन्य डेटा स्रोतों के साथ संयोजन के लिए GraphQL संघटन का समर्थन करना चाहिए?
|
||||
यह संरचित और ग्राफ डेटा में एकीकृत क्वेरी को सक्षम करेगा
|
||||
|
||||
4. **सदस्यता समर्थन**: क्या सेवा को वास्तविक समय अपडेट के लिए GraphQL सदस्यता का समर्थन करना चाहिए?
|
||||
इसके लिए गेटवे में WebSocket समर्थन की आवश्यकता होगी
|
||||
|
||||
5. **कस्टम स्केलर**: क्या डोमेन-विशिष्ट डेटा प्रकारों के लिए कस्टम स्केलर प्रकारों का समर्थन किया जाना चाहिए?
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
उदाहरण: DateTime, UUID, JSON फ़ील्ड
|
||||
|
||||
## संदर्भ
|
||||
|
||||
<<<<<<< HEAD
|
||||
स्ट्रक्चर्ड डेटा तकनीकी विनिर्देश: `docs/tech-specs/structured-data.md`
|
||||
स्ट्रॉबेरी GraphQL दस्तावेज़: https://strawberry.rocks/
|
||||
GraphQL विनिर्देश: https://spec.graphql.org/
|
||||
अपाचे कैसेंड्रा CQL संदर्भ: https://cassandra.apache.org/doc/stable/cassandra/cql/
|
||||
ट्रस्टग्राफ फ्लो प्रोसेसर दस्तावेज़: आंतरिक दस्तावेज़
|
||||
=======
|
||||
संरचित डेटा तकनीकी विनिर्देश: `docs/tech-specs/structured-data.md`
|
||||
स्ट्रॉबेरी GraphQL दस्तावेज़ीकरण: https://strawberry.rocks/
|
||||
GraphQL विनिर्देश: https://spec.graphql.org/
|
||||
Apache Cassandra CQL संदर्भ: https://cassandra.apache.org/doc/stable/cassandra/cql/
|
||||
TrustGraph फ्लो प्रोसेसर दस्तावेज़ीकरण: आंतरिक दस्तावेज़ीकरण
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
759
docs/tech-specs/hi/graphrag-performance-optimization.hi.md
Normal file
759
docs/tech-specs/hi/graphrag-performance-optimization.hi.md
Normal file
|
|
@ -0,0 +1,759 @@
|
|||
---
|
||||
layout: default
|
||||
title: "ग्राफआरएजी प्रदर्शन अनुकूलन तकनीकी विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# ग्राफआरएजी प्रदर्शन अनुकूलन तकनीकी विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह विनिर्देश ट्रस्टग्राफ में ग्राफआरएजी (ग्राफ रिट्रीवल-ऑगमेंटेड जनरेशन) एल्गोरिदम के लिए व्यापक प्रदर्शन अनुकूलन का वर्णन करता है। वर्तमान कार्यान्वयन में महत्वपूर्ण प्रदर्शन बाधाएं हैं जो स्केलेबिलिटी और प्रतिक्रिया समय को सीमित करती हैं। यह विनिर्देश चार प्राथमिक अनुकूलन क्षेत्रों को संबोधित करता है:
|
||||
|
||||
1. **ग्राफ ट्रैवर्सल अनुकूलन**: अक्षम पुनरावर्ती डेटाबेस प्रश्नों को समाप्त करें और बैच में ग्राफ अन्वेषण लागू करें।
|
||||
2. **लेबल रिज़ॉल्यूशन अनुकूलन**: क्रमिक लेबल फ़ेचिंग को समानांतर/बैच संचालन से बदलें।
|
||||
3. **कैशिंग रणनीति में सुधार**: एलआरयू निष्कासन और प्रीफ़ेचिंग के साथ बुद्धिमान कैशिंग लागू करें।
|
||||
4. **क्वेरी अनुकूलन**: बेहतर प्रतिक्रिया समय के लिए परिणाम मेमोइज़ेशन और एम्बेडिंग कैशिंग जोड़ें।
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
<<<<<<< HEAD
|
||||
**डेटाबेस क्वेरी की मात्रा को कम करें**: बैचिंग और कैशिंग के माध्यम से कुल डेटाबेस प्रश्नों में 50-80% की कमी प्राप्त करें।
|
||||
**प्रतिक्रिया समय में सुधार**: सबग्राफ निर्माण और लेबल रिज़ॉल्यूशन में 3-5 गुना तेजी और 2-3 गुना तेजी लाने का लक्ष्य रखें।
|
||||
**स्केलेबिलिटी में वृद्धि**: बेहतर मेमोरी प्रबंधन के साथ बड़े नॉलेज ग्राफ का समर्थन करें।
|
||||
**सटीकता बनाए रखें**: मौजूदा ग्राफआरएजी कार्यक्षमता और परिणाम गुणवत्ता को संरक्षित करें।
|
||||
**समवर्तीता सक्षम करें**: एकाधिक समवर्ती अनुरोधों के लिए समानांतर प्रसंस्करण क्षमताओं में सुधार करें।
|
||||
**मेमोरी पदचिह्न को कम करें**: कुशल डेटा संरचनाओं और मेमोरी प्रबंधन को लागू करें।
|
||||
=======
|
||||
**डेटाबेस क्वेरी की मात्रा कम करें**: बैचिंग और कैशिंग के माध्यम से कुल डेटाबेस प्रश्नों में 50-80% की कमी प्राप्त करें।
|
||||
**प्रतिक्रिया समय में सुधार**: सबग्राफ निर्माण और लेबल रिज़ॉल्यूशन में 3-5 गुना तेजी और 2-3 गुना तेजी लाने का लक्ष्य रखें।
|
||||
**स्केलेबिलिटी बढ़ाएं**: बेहतर मेमोरी प्रबंधन के साथ बड़े नॉलेज ग्राफ का समर्थन करें।
|
||||
**सटीकता बनाए रखें**: मौजूदा ग्राफआरएजी कार्यक्षमता और परिणाम गुणवत्ता को संरक्षित करें।
|
||||
**समवर्तीता सक्षम करें**: एकाधिक समवर्ती अनुरोधों के लिए समानांतर प्रसंस्करण क्षमताओं में सुधार करें।
|
||||
**मेमोरी पदचिह्न कम करें**: कुशल डेटा संरचनाओं और मेमोरी प्रबंधन को लागू करें।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**अवलोकनशीलता जोड़ें**: प्रदर्शन मेट्रिक्स और निगरानी क्षमताओं को शामिल करें।
|
||||
**विश्वसनीयता सुनिश्चित करें**: उचित त्रुटि हैंडलिंग और टाइमआउट तंत्र जोड़ें।
|
||||
|
||||
## पृष्ठभूमि
|
||||
|
||||
`trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py` में वर्तमान ग्राफआरएजी कार्यान्वयन में कई महत्वपूर्ण प्रदर्शन मुद्दे हैं जो सिस्टम स्केलेबिलिटी को गंभीर रूप से प्रभावित करते हैं:
|
||||
|
||||
### वर्तमान प्रदर्शन समस्याएं
|
||||
|
||||
**1. अक्षम ग्राफ ट्रैवर्सल (`follow_edges` फ़ंक्शन, लाइनें 79-127)**
|
||||
<<<<<<< HEAD
|
||||
प्रत्येक इकाई प्रति गहराई स्तर के लिए 3 अलग-अलग डेटाबेस क्वेरी करता है।
|
||||
क्वेरी पैटर्न: प्रत्येक इकाई के लिए विषय-आधारित, विधेय-आधारित और ऑब्जेक्ट-आधारित क्वेरी।
|
||||
कोई बैचिंग नहीं: प्रत्येक क्वेरी एक समय में केवल एक इकाई को संसाधित करती है।
|
||||
=======
|
||||
प्रति इकाई प्रति गहराई स्तर के लिए 3 अलग-अलग डेटाबेस क्वेरी करता है।
|
||||
क्वेरी पैटर्न: प्रत्येक इकाई के लिए विषय-आधारित, विधेय-आधारित और ऑब्जेक्ट-आधारित क्वेरी।
|
||||
कोई बैचिंग नहीं: प्रत्येक क्वेरी केवल एक इकाई को संसाधित करती है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
कोई चक्र का पता नहीं: समान नोड्स को कई बार फिर से देख सकता है।
|
||||
मेमोइज़ेशन के बिना पुनरावर्ती कार्यान्वयन घातीय जटिलता की ओर ले जाता है।
|
||||
समय जटिलता: O(entities × max_path_length × triple_limit³)
|
||||
|
||||
**2. क्रमिक लेबल रिज़ॉल्यूशन (`get_labelgraph` फ़ंक्शन, लाइनें 144-171)**
|
||||
प्रत्येक ट्रिपल घटक (विषय, विधेय, ऑब्जेक्ट) को क्रमिक रूप से संसाधित करता है।
|
||||
प्रत्येक `maybe_label` कॉल संभावित रूप से एक डेटाबेस क्वेरी को ट्रिगर करता है।
|
||||
लेबल क्वेरी के समानांतर निष्पादन या बैचिंग नहीं।
|
||||
परिणाम में subgraph_size × 3 व्यक्तिगत डेटाबेस कॉल होते हैं।
|
||||
|
||||
**3. आदिम कैशिंग रणनीति (`maybe_label` फ़ंक्शन, लाइनें 62-77)**
|
||||
आकार सीमा या टीटीएल के बिना एक साधारण शब्दकोश कैश।
|
||||
<<<<<<< HEAD
|
||||
कोई कैश निष्कासन नीति नहीं जिसके परिणामस्वरूप असीमित मेमोरी वृद्धि होती है।
|
||||
=======
|
||||
कोई कैश निष्कासन नीति असीमित मेमोरी वृद्धि की ओर ले जाती है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
कैश मिस व्यक्तिगत डेटाबेस क्वेरी को ट्रिगर करते हैं।
|
||||
कोई प्रीफ़ेचिंग या बुद्धिमान कैश वार्मिंग नहीं।
|
||||
|
||||
**4. उप-इष्टतम क्वेरी पैटर्न**
|
||||
समान अनुरोधों के बीच इकाई वेक्टर समानता क्वेरी कैश नहीं की जाती हैं।
|
||||
दोहराए गए क्वेरी पैटर्न के लिए कोई परिणाम मेमोइज़ेशन नहीं।
|
||||
सामान्य एक्सेस पैटर्न के लिए कोई क्वेरी अनुकूलन नहीं।
|
||||
|
||||
**5. महत्वपूर्ण ऑब्जेक्ट लाइफटाइम मुद्दे (`rag.py:96-102`)**
|
||||
**प्रत्येक अनुरोध के लिए GraphRag ऑब्जेक्ट फिर से बनाया गया**: प्रत्येक क्वेरी के लिए एक नया उदाहरण बनाया जाता है, जिससे सभी कैश लाभ खो जाते हैं।
|
||||
<<<<<<< HEAD
|
||||
**क्वेरी ऑब्जेक्ट बहुत कम समय तक रहता है**: एकल क्वेरी निष्पादन के भीतर बनाया और नष्ट किया जाता है (लाइनें 201-207)।
|
||||
=======
|
||||
**क्वेरी ऑब्जेक्ट बहुत कम समय तक जीवित रहता है**: एक ही क्वेरी निष्पादन के भीतर बनाया और नष्ट किया जाता है (लाइनें 201-207)।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**प्रत्येक अनुरोध के लिए लेबल कैश रीसेट**: कैश वार्मिंग और संचित ज्ञान के बीच खो जाता है।
|
||||
**क्लाइंट पुन: निर्माण ओवरहेड**: प्रत्येक अनुरोध के लिए डेटाबेस क्लाइंट संभावित रूप से फिर से स्थापित होते हैं।
|
||||
**क्रॉस-रिक्वेस्ट अनुकूलन नहीं**: क्वेरी पैटर्न या परिणाम साझाकरण से लाभ नहीं उठाया जा सकता है।
|
||||
|
||||
### प्रदर्शन प्रभाव विश्लेषण
|
||||
|
||||
एक विशिष्ट क्वेरी के लिए वर्तमान सबसे खराब स्थिति परिदृश्य:
|
||||
<<<<<<< HEAD
|
||||
**इकाई पुनर्प्राप्ति**: 1 वेक्टर समानता क्वेरी
|
||||
**ग्राफ ट्रैवर्सल**: entities × max_path_length × 3 × triple_limit क्वेरी
|
||||
**लेबल रिज़ॉल्यूशन**: subgraph_size × 3 व्यक्तिगत लेबल क्वेरी
|
||||
|
||||
डिफ़ॉल्ट मापदंडों के लिए (50 एंटिटीज, पथ लंबाई 2, 30 ट्रिपल सीमा, 150 सबग्राफ आकार):
|
||||
**न्यूनतम क्वेरीज़**: 1 + (50 × 2 × 3 × 30) + (150 × 3) = **9,451 डेटाबेस क्वेरीज़**
|
||||
**प्रतिक्रिया समय**: मध्यम आकार के ग्राफ़ के लिए 15-30 सेकंड
|
||||
**मेमोरी उपयोग**: समय के साथ असीमित कैश वृद्धि
|
||||
**कैश प्रभावशीलता**: 0% - प्रत्येक अनुरोध पर कैश रीसेट हो जाते हैं
|
||||
**ऑब्जेक्ट निर्माण ओवरहेड**: प्रति अनुरोध बनाए गए/विनाशित GraphRag + Query ऑब्जेक्ट
|
||||
|
||||
यह विनिर्देश इन कमियों को बैच क्वेरी, बुद्धिमान कैशिंग और समानांतर प्रसंस्करण को लागू करके संबोधित करता है। क्वेरी पैटर्न और डेटा एक्सेस को अनुकूलित करके, TrustGraph निम्न कार्य कर सकता है:
|
||||
लाखों एंटिटीज वाले एंटरप्राइज-स्केल नॉलेज ग्राफ़ का समर्थन करें
|
||||
विशिष्ट क्वेरीज़ के लिए उप-सेकंड प्रतिक्रिया समय प्रदान करें
|
||||
सैकड़ों समवर्ती GraphRAG अनुरोधों को संभालें
|
||||
ग्राफ के आकार और जटिलता के साथ कुशलतापूर्वक स्केल करें
|
||||
=======
|
||||
**इकाई पुनर्प्राप्ति**: 1 वेक्टर समानता क्वेरी।
|
||||
**ग्राफ ट्रैवर्सल**: entities × max_path_length × 3 × triple_limit क्वेरी।
|
||||
**लेबल रिज़ॉल्यूशन**: subgraph_size × 3 व्यक्तिगत लेबल क्वेरी।
|
||||
|
||||
डिफ़ॉल्ट मापदंडों के लिए (50 एंटिटीज, पथ लंबाई 2, 30 ट्रिपल सीमा, 150 सबग्राफ आकार):
|
||||
**न्यूनतम क्वेरीज़**: 1 + (50 × 2 × 3 × 30) + (150 × 3) = **9,451 डेटाबेस क्वेरीज़**
|
||||
**प्रतिक्रिया समय**: मध्यम आकार के ग्राफ के लिए 15-30 सेकंड
|
||||
**मेमोरी उपयोग**: समय के साथ असीमित कैश वृद्धि
|
||||
**कैश प्रभावशीलता**: 0% - प्रत्येक अनुरोध पर कैश रीसेट हो जाते हैं
|
||||
**ऑब्जेक्ट निर्माण ओवरहेड**: प्रति अनुरोध बनाए गए/विनाश किए गए ग्राफराग + क्वेरी ऑब्जेक्ट
|
||||
|
||||
यह विनिर्देश इन कमियों को बैच क्वेरी, बुद्धिमान कैशिंग और समानांतर प्रसंस्करण को लागू करके संबोधित करता है। क्वेरी पैटर्न और डेटा एक्सेस को अनुकूलित करके, ट्रस्टग्राफ निम्न कार्य कर सकता है:
|
||||
लाखों एंटिटीज वाले एंटरप्राइज-स्केल नॉलेज ग्राफ का समर्थन करें
|
||||
विशिष्ट क्वेरीज़ के लिए उप-सेकंड प्रतिक्रिया समय प्रदान करें
|
||||
सैकड़ों समवर्ती ग्राफराग अनुरोधों को संभालें
|
||||
ग्राफ आकार और जटिलता के साथ कुशलतापूर्वक स्केल करें
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## तकनीकी डिज़ाइन
|
||||
|
||||
### आर्किटेक्चर
|
||||
|
||||
<<<<<<< HEAD
|
||||
GraphRAG प्रदर्शन अनुकूलन के लिए निम्नलिखित तकनीकी घटकों की आवश्यकता होती है:
|
||||
|
||||
#### 1. **ऑब्जेक्ट लाइफटाइम आर्किटेक्चरल रीफैक्टर**
|
||||
**GraphRag को लंबे समय तक चलने वाला बनाएं**: GraphRag इंस्टेंस को प्रोसेसर स्तर पर ले जाएं ताकि यह अनुरोधों के बीच बना रहे
|
||||
**कैश बनाए रखें**: लेबल कैश, एम्बेडिंग कैश और क्वेरी परिणाम कैश को अनुरोधों के बीच बनाए रखें
|
||||
**क्वेरी ऑब्जेक्ट को अनुकूलित करें**: Query को एक हल्के निष्पादन संदर्भ के रूप में रीफैक्टर करें, डेटा कंटेनर के रूप में नहीं
|
||||
=======
|
||||
ग्राफराग प्रदर्शन अनुकूलन के लिए निम्नलिखित तकनीकी घटकों की आवश्यकता होती है:
|
||||
|
||||
#### 1. **ऑब्जेक्ट लाइफटाइम आर्किटेक्चरल रीफैक्टर**
|
||||
**ग्राफराग को लंबे समय तक चलने वाला बनाएं**: ग्राफराग इंस्टेंस को प्रोसेसर स्तर पर ले जाएं ताकि यह अनुरोधों के बीच बना रहे
|
||||
**कैश बनाए रखें**: लेबल कैश, एम्बेडिंग कैश और क्वेरी परिणाम कैश को अनुरोधों के बीच बनाए रखें
|
||||
**क्वेरी ऑब्जेक्ट को अनुकूलित करें**: क्वेरी को एक हल्के निष्पादन संदर्भ के रूप में रीफैक्टर करें, डेटा कंटेनर के रूप में नहीं
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**कनेक्शन दृढ़ता**: डेटाबेस क्लाइंट कनेक्शन को अनुरोधों के बीच बनाए रखें
|
||||
|
||||
मॉड्यूल: `trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py` (संशोधित)
|
||||
|
||||
#### 2. **अनुकूलित ग्राफ ट्रैवर्सल इंजन**
|
||||
पुनरावर्ती `follow_edges` को पुनरावृत्त चौड़ाई-पहली खोज से बदलें
|
||||
प्रत्येक ट्रैवर्सल स्तर पर बैच एंटिटी प्रोसेसिंग लागू करें
|
||||
देखे गए नोड ट्रैकिंग का उपयोग करके चक्र का पता लगाएं
|
||||
सीमाओं तक पहुंचने पर प्रारंभिक समाप्ति शामिल करें
|
||||
|
||||
मॉड्यूल: `trustgraph-flow/trustgraph/retrieval/graph_rag/optimized_traversal.py`
|
||||
|
||||
#### 3. **समानांतर लेबल रिज़ॉल्यूशन सिस्टम**
|
||||
<<<<<<< HEAD
|
||||
एक साथ कई एंटिटीज के लिए लेबल क्वेरीज़ को बैच करें
|
||||
=======
|
||||
एक साथ कई एंटिटीज के लिए बैच लेबल क्वेरी
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
समवर्ती डेटाबेस एक्सेस के लिए एसिंक्रोनस/अवेट पैटर्न लागू करें
|
||||
सामान्य लेबल पैटर्न के लिए बुद्धिमान प्रीफ़ेटिंग जोड़ें
|
||||
लेबल कैश वार्मिंग रणनीतियों शामिल करें
|
||||
|
||||
मॉड्यूल: `trustgraph-flow/trustgraph/retrieval/graph_rag/label_resolver.py`
|
||||
|
||||
#### 4. **रूढ़िवादी लेबल कैशिंग लेयर**
|
||||
<<<<<<< HEAD
|
||||
प्रदर्शन बनाम स्थिरता को संतुलित करने के लिए केवल लेबल के लिए लघु TTL के साथ LRU कैश (5 मिनट)
|
||||
कैश मेट्रिक्स और हिट अनुपात निगरानी
|
||||
**कोई एम्बेडिंग कैशिंग नहीं**: पहले से ही प्रति-क्वेरी कैश किया गया है, कोई क्रॉस-क्वेरी लाभ नहीं
|
||||
**कोई क्वेरी परिणाम कैशिंग नहीं**: ग्राफ परिवर्तन स्थिरता संबंधी चिंताओं के कारण
|
||||
=======
|
||||
केवल लेबल के लिए लघु TTL के साथ LRU कैश (5 मिनट) प्रदर्शन बनाम स्थिरता को संतुलित करने के लिए
|
||||
कैश मेट्रिक्स और हिट अनुपात निगरानी
|
||||
**कोई एम्बेडिंग कैशिंग नहीं**: पहले से ही प्रति-क्वेरी कैश किया गया है, कोई क्रॉस-क्वेरी लाभ नहीं
|
||||
**कोई क्वेरी परिणाम कैशिंग नहीं**: ग्राफ उत्परिवर्तन स्थिरता संबंधी चिंताओं के कारण
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
मॉड्यूल: `trustgraph-flow/trustgraph/retrieval/graph_rag/cache_manager.py`
|
||||
|
||||
#### 5. **क्वेरी अनुकूलन ढांचा**
|
||||
क्वेरी पैटर्न विश्लेषण और अनुकूलन सुझाव
|
||||
डेटाबेस एक्सेस के लिए बैच क्वेरी समन्वयक
|
||||
कनेक्शन पूलिंग और क्वेरी टाइमआउट प्रबंधन
|
||||
प्रदर्शन निगरानी और मेट्रिक्स संग्रह
|
||||
|
||||
मॉड्यूल: `trustgraph-flow/trustgraph/retrieval/graph_rag/query_optimizer.py`
|
||||
|
||||
### डेटा मॉडल
|
||||
|
||||
#### अनुकूलित ग्राफ ट्रैवर्सल स्थिति
|
||||
|
||||
ट्रैवर्सल इंजन अनावश्यक कार्यों से बचने के लिए स्थिति बनाए रखता है:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class TraversalState:
|
||||
visited_entities: Set[str]
|
||||
current_level_entities: Set[str]
|
||||
next_level_entities: Set[str]
|
||||
subgraph: Set[Tuple[str, str, str]]
|
||||
depth: int
|
||||
query_batch: List[TripleQuery]
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
यह दृष्टिकोण निम्नलिखित सुविधाएँ प्रदान करता है:
|
||||
=======
|
||||
यह दृष्टिकोण निम्नलिखित कार्य करने की अनुमति देता है:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
विज़िट किए गए एंटिटी को ट्रैक करके कुशल चक्र का पता लगाना
|
||||
प्रत्येक ट्रैवर्सल स्तर पर बैच में क्वेरी तैयार करना
|
||||
मेमोरी-कुशल स्थिति प्रबंधन
|
||||
जब आकार की सीमाएँ पूरी हो जाती हैं तो प्रारंभिक समाप्ति
|
||||
|
||||
#### बेहतर कैश संरचना
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class CacheEntry:
|
||||
value: Any
|
||||
timestamp: float
|
||||
access_count: int
|
||||
ttl: Optional[float]
|
||||
|
||||
class CacheManager:
|
||||
label_cache: LRUCache[str, CacheEntry]
|
||||
embedding_cache: LRUCache[str, CacheEntry]
|
||||
query_result_cache: LRUCache[str, CacheEntry]
|
||||
cache_stats: CacheStatistics
|
||||
```
|
||||
|
||||
#### बैच क्वेरी संरचनाएं
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class BatchTripleQuery:
|
||||
entities: List[str]
|
||||
query_type: QueryType # SUBJECT, PREDICATE, OBJECT
|
||||
limit_per_entity: int
|
||||
|
||||
@dataclass
|
||||
class BatchLabelQuery:
|
||||
entities: List[str]
|
||||
predicate: str = LABEL
|
||||
```
|
||||
|
||||
### एपीआई (APIs)
|
||||
|
||||
#### नए एपीआई (New APIs):
|
||||
|
||||
**ग्राफ ट्रावर्सल एपीआई (GraphTraversal API)**
|
||||
```python
|
||||
async def optimized_follow_edges_batch(
|
||||
entities: List[str],
|
||||
max_depth: int,
|
||||
triple_limit: int,
|
||||
max_subgraph_size: int
|
||||
) -> Set[Tuple[str, str, str]]
|
||||
```
|
||||
|
||||
**बैच लेबल रिज़ॉल्यूशन एपीआई**
|
||||
```python
|
||||
async def resolve_labels_batch(
|
||||
entities: List[str],
|
||||
cache_manager: CacheManager
|
||||
) -> Dict[str, str]
|
||||
```
|
||||
|
||||
**कैश प्रबंधन एपीआई**
|
||||
```python
|
||||
class CacheManager:
|
||||
async def get_or_fetch_label(self, entity: str) -> str
|
||||
async def get_or_fetch_embeddings(self, query: str) -> List[float]
|
||||
async def cache_query_result(self, query_hash: str, result: Any, ttl: int)
|
||||
def get_cache_statistics(self) -> CacheStatistics
|
||||
```
|
||||
|
||||
#### संशोधित एपीआई:
|
||||
|
||||
**GraphRag.query()** - प्रदर्शन अनुकूलन के साथ बेहतर:
|
||||
कैश नियंत्रण के लिए `cache_manager` पैरामीटर जोड़ें
|
||||
`performance_metrics` रिटर्न वैल्यू शामिल करें
|
||||
विश्वसनीयता के लिए `query_timeout` पैरामीटर जोड़ें
|
||||
|
||||
**क्वेरी क्लास** - बैच प्रोसेसिंग के लिए पुनर्गठित:
|
||||
व्यक्तिगत इकाई प्रसंस्करण को बैच ऑपरेशनों से बदलें
|
||||
<<<<<<< HEAD
|
||||
संसाधन सफाई के लिए एसिंक्रोनस कॉन्टेक्स्ट मैनेजर जोड़ें
|
||||
=======
|
||||
संसाधन सफाई के लिए एसिंक्रोनस संदर्भ प्रबंधक जोड़ें
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
लंबे समय तक चलने वाले ऑपरेशनों के लिए प्रगति कॉलबैक शामिल करें
|
||||
|
||||
### कार्यान्वयन विवरण
|
||||
|
||||
<<<<<<< HEAD
|
||||
#### चरण 0: महत्वपूर्ण आर्किटेक्चरल लाइफटाइम रिफैक्टर
|
||||
=======
|
||||
#### चरण 0: महत्वपूर्ण वास्तुशिल्प जीवनचक्र पुनर्गठन
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**वर्तमान समस्याग्रस्त कार्यान्वयन:**
|
||||
```python
|
||||
# INEFFICIENT: GraphRag recreated every request
|
||||
class Processor(FlowProcessor):
|
||||
async def on_request(self, msg, consumer, flow):
|
||||
# PROBLEM: New GraphRag instance per request!
|
||||
self.rag = GraphRag(
|
||||
embeddings_client = flow("embeddings-request"),
|
||||
graph_embeddings_client = flow("graph-embeddings-request"),
|
||||
triples_client = flow("triples-request"),
|
||||
prompt_client = flow("prompt-request"),
|
||||
verbose=True,
|
||||
)
|
||||
# Cache starts empty every time - no benefit from previous requests
|
||||
response = await self.rag.query(...)
|
||||
|
||||
# VERY SHORT-LIVED: Query object created/destroyed per request
|
||||
class GraphRag:
|
||||
async def query(self, query, user="trustgraph", collection="default", ...):
|
||||
q = Query(rag=self, user=user, collection=collection, ...) # Created
|
||||
kg = await q.get_labelgraph(query) # Used briefly
|
||||
# q automatically destroyed when function exits
|
||||
```
|
||||
|
||||
**अनुकूलित, दीर्घकालिक संरचना:**
|
||||
```python
|
||||
class Processor(FlowProcessor):
|
||||
def __init__(self, **params):
|
||||
super().__init__(**params)
|
||||
self.rag_instance = None # Will be initialized once
|
||||
self.client_connections = {}
|
||||
|
||||
async def initialize_rag(self, flow):
|
||||
"""Initialize GraphRag once, reuse for all requests"""
|
||||
if self.rag_instance is None:
|
||||
self.rag_instance = LongLivedGraphRag(
|
||||
embeddings_client=flow("embeddings-request"),
|
||||
graph_embeddings_client=flow("graph-embeddings-request"),
|
||||
triples_client=flow("triples-request"),
|
||||
prompt_client=flow("prompt-request"),
|
||||
verbose=True,
|
||||
)
|
||||
return self.rag_instance
|
||||
|
||||
async def on_request(self, msg, consumer, flow):
|
||||
# REUSE the same GraphRag instance - caches persist!
|
||||
rag = await self.initialize_rag(flow)
|
||||
|
||||
# Query object becomes lightweight execution context
|
||||
response = await rag.query_with_context(
|
||||
query=v.query,
|
||||
execution_context=QueryContext(
|
||||
user=v.user,
|
||||
collection=v.collection,
|
||||
entity_limit=entity_limit,
|
||||
# ... other params
|
||||
)
|
||||
)
|
||||
|
||||
class LongLivedGraphRag:
|
||||
def __init__(self, ...):
|
||||
# CONSERVATIVE caches - balance performance vs consistency
|
||||
self.label_cache = LRUCacheWithTTL(max_size=5000, ttl=300) # 5min TTL for freshness
|
||||
# Note: No embedding cache - already cached per-query, no cross-query benefit
|
||||
# Note: No query result cache due to consistency concerns
|
||||
self.performance_metrics = PerformanceTracker()
|
||||
|
||||
async def query_with_context(self, query: str, context: QueryContext):
|
||||
# Use lightweight QueryExecutor instead of heavyweight Query object
|
||||
executor = QueryExecutor(self, context) # Minimal object
|
||||
return await executor.execute(query)
|
||||
|
||||
@dataclass
|
||||
class QueryContext:
|
||||
"""Lightweight execution context - no heavy operations"""
|
||||
user: str
|
||||
collection: str
|
||||
entity_limit: int
|
||||
triple_limit: int
|
||||
max_subgraph_size: int
|
||||
max_path_length: int
|
||||
|
||||
class QueryExecutor:
|
||||
"""Lightweight execution context - replaces old Query class"""
|
||||
def __init__(self, rag: LongLivedGraphRag, context: QueryContext):
|
||||
self.rag = rag
|
||||
self.context = context
|
||||
# No heavy initialization - just references
|
||||
|
||||
async def execute(self, query: str):
|
||||
# All heavy lifting uses persistent rag caches
|
||||
return await self.rag.execute_optimized_query(query, self.context)
|
||||
```
|
||||
|
||||
यह वास्तुशिल्पीय परिवर्तन निम्नलिखित सुविधाएँ प्रदान करता है:
|
||||
**सामान्य संबंधों वाले ग्राफों के लिए डेटाबेस क्वेरी में 10-20% की कमी** (वर्तमान में 0% की तुलना में)
|
||||
प्रत्येक अनुरोध के लिए **ऑब्जेक्ट निर्माण ओवरहेड को समाप्त करना**
|
||||
**स्थायी कनेक्शन पूलिंग** और क्लाइंट पुन: उपयोग
|
||||
**कैश टीटीएल विंडो के भीतर क्रॉस-अनुरोध अनुकूलन**
|
||||
|
||||
**महत्वपूर्ण कैश स्थिरता सीमा:**
|
||||
<<<<<<< HEAD
|
||||
दीर्घकालिक कैशिंग से अप्रचलन का जोखिम होता है जब अंतर्निहित ग्राफ में एंटिटीज/लेबल हटा दिए जाते हैं या संशोधित किए जाते हैं। एलआरयू कैश जिसमें टीटीएल है, प्रदर्शन लाभ और डेटा ताज़गी के बीच संतुलन प्रदान करता है, लेकिन यह वास्तविक समय में ग्राफ परिवर्तनों का पता नहीं लगा सकता है।
|
||||
=======
|
||||
दीर्घकालिक कैशिंग से पुरानी जानकारी का जोखिम होता है जब अंतर्निहित ग्राफ में एंटिटीज/लेबल हटा दिए जाते हैं या संशोधित किए जाते हैं। एलआरयू कैश, टीटीएल के साथ, प्रदर्शन लाभ और डेटा ताज़गी के बीच एक संतुलन प्रदान करता है, लेकिन यह वास्तविक समय में ग्राफ परिवर्तनों का पता नहीं लगा सकता है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
#### चरण 1: ग्राफ ट्रैवर्सल अनुकूलन
|
||||
|
||||
**वर्तमान कार्यान्वयन समस्याएं:**
|
||||
```python
|
||||
# INEFFICIENT: 3 queries per entity per level
|
||||
async def follow_edges(self, ent, subgraph, path_length):
|
||||
# Query 1: s=ent, p=None, o=None
|
||||
res = await self.rag.triples_client.query(s=ent, p=None, o=None, limit=self.triple_limit)
|
||||
# Query 2: s=None, p=ent, o=None
|
||||
res = await self.rag.triples_client.query(s=None, p=ent, o=None, limit=self.triple_limit)
|
||||
# Query 3: s=None, p=None, o=ent
|
||||
res = await self.rag.triples_client.query(s=None, p=None, o=ent, limit=self.triple_limit)
|
||||
```
|
||||
|
||||
**अनुकूलित कार्यान्वयन:**
|
||||
```python
|
||||
async def optimized_traversal(self, entities: List[str], max_depth: int) -> Set[Triple]:
|
||||
visited = set()
|
||||
current_level = set(entities)
|
||||
subgraph = set()
|
||||
|
||||
for depth in range(max_depth):
|
||||
if not current_level or len(subgraph) >= self.max_subgraph_size:
|
||||
break
|
||||
|
||||
# Batch all queries for current level
|
||||
batch_queries = []
|
||||
for entity in current_level:
|
||||
if entity not in visited:
|
||||
batch_queries.extend([
|
||||
TripleQuery(s=entity, p=None, o=None),
|
||||
TripleQuery(s=None, p=entity, o=None),
|
||||
TripleQuery(s=None, p=None, o=entity)
|
||||
])
|
||||
|
||||
# Execute all queries concurrently
|
||||
results = await self.execute_batch_queries(batch_queries)
|
||||
|
||||
# Process results and prepare next level
|
||||
next_level = set()
|
||||
for result in results:
|
||||
subgraph.update(result.triples)
|
||||
next_level.update(result.new_entities)
|
||||
|
||||
visited.update(current_level)
|
||||
current_level = next_level - visited
|
||||
|
||||
return subgraph
|
||||
```
|
||||
|
||||
#### चरण 2: समानांतर लेबल समाधान
|
||||
|
||||
**वर्तमान अनुक्रमिक कार्यान्वयन:**
|
||||
```python
|
||||
# INEFFICIENT: Sequential processing
|
||||
for edge in subgraph:
|
||||
s = await self.maybe_label(edge[0]) # Individual query
|
||||
p = await self.maybe_label(edge[1]) # Individual query
|
||||
o = await self.maybe_label(edge[2]) # Individual query
|
||||
```
|
||||
|
||||
**अनुकूलित समानांतर कार्यान्वयन:**
|
||||
```python
|
||||
async def resolve_labels_parallel(self, subgraph: List[Triple]) -> List[Triple]:
|
||||
# Collect all unique entities needing labels
|
||||
entities_to_resolve = set()
|
||||
for s, p, o in subgraph:
|
||||
entities_to_resolve.update([s, p, o])
|
||||
|
||||
# Remove already cached entities
|
||||
uncached_entities = [e for e in entities_to_resolve if e not in self.label_cache]
|
||||
|
||||
# Batch query for all uncached labels
|
||||
if uncached_entities:
|
||||
label_results = await self.batch_label_query(uncached_entities)
|
||||
self.label_cache.update(label_results)
|
||||
|
||||
# Apply labels to subgraph
|
||||
return [
|
||||
(self.label_cache.get(s, s), self.label_cache.get(p, p), self.label_cache.get(o, o))
|
||||
for s, p, o in subgraph
|
||||
]
|
||||
```
|
||||
|
||||
#### चरण 3: उन्नत कैशिंग रणनीति
|
||||
|
||||
**एलआरयू (LRU) कैश टीटीएल (TTL) के साथ:**
|
||||
```python
|
||||
class LRUCacheWithTTL:
|
||||
def __init__(self, max_size: int, default_ttl: int = 3600):
|
||||
self.cache = OrderedDict()
|
||||
self.max_size = max_size
|
||||
self.default_ttl = default_ttl
|
||||
self.access_times = {}
|
||||
|
||||
async def get(self, key: str) -> Optional[Any]:
|
||||
if key in self.cache:
|
||||
# Check TTL expiration
|
||||
if time.time() - self.access_times[key] > self.default_ttl:
|
||||
del self.cache[key]
|
||||
del self.access_times[key]
|
||||
return None
|
||||
|
||||
# Move to end (most recently used)
|
||||
self.cache.move_to_end(key)
|
||||
return self.cache[key]
|
||||
return None
|
||||
|
||||
async def put(self, key: str, value: Any):
|
||||
if key in self.cache:
|
||||
self.cache.move_to_end(key)
|
||||
else:
|
||||
if len(self.cache) >= self.max_size:
|
||||
# Remove least recently used
|
||||
oldest_key = next(iter(self.cache))
|
||||
del self.cache[oldest_key]
|
||||
del self.access_times[oldest_key]
|
||||
|
||||
self.cache[key] = value
|
||||
self.access_times[key] = time.time()
|
||||
```
|
||||
|
||||
#### चरण 4: क्वेरी अनुकूलन और निगरानी
|
||||
|
||||
**प्रदर्शन मेट्रिक्स संग्रह:**
|
||||
```python
|
||||
@dataclass
|
||||
class PerformanceMetrics:
|
||||
total_queries: int
|
||||
cache_hits: int
|
||||
cache_misses: int
|
||||
avg_response_time: float
|
||||
subgraph_construction_time: float
|
||||
label_resolution_time: float
|
||||
total_entities_processed: int
|
||||
memory_usage_mb: float
|
||||
```
|
||||
|
||||
**क्वेरी टाइमआउट और सर्किट ब्रेकर:**
|
||||
```python
|
||||
async def execute_with_timeout(self, query_func, timeout: int = 30):
|
||||
try:
|
||||
return await asyncio.wait_for(query_func(), timeout=timeout)
|
||||
except asyncio.TimeoutError:
|
||||
logger.error(f"Query timeout after {timeout}s")
|
||||
raise GraphRagTimeoutError(f"Query exceeded timeout of {timeout}s")
|
||||
```
|
||||
|
||||
## कैश कंसिस्टेंसी पर विचार
|
||||
|
||||
**डेटा स्टेलनेस ट्रेड-ऑफ:**
|
||||
<<<<<<< HEAD
|
||||
**लेबल कैश (5 मिनट TTL)**: डिलीट किए गए/रीनेम किए गए एंटिटी लेबल को प्रदर्शित करने का जोखिम।
|
||||
**कोई एम्बेडिंग कैशिंग नहीं:** आवश्यक नहीं है - एम्बेडिंग पहले से ही प्रति-क्वेरी कैश किए गए हैं।
|
||||
**कोई परिणाम कैशिंग नहीं:** डिलीट किए गए एंटिटीज/रिलेशनशिप से पुराने सबग्राफ परिणामों को रोकता है।
|
||||
=======
|
||||
**लेबल कैश (5 मिनट TTL)**: हटाए गए/पुनर्नाम किए गए एंटिटी लेबल को प्रदर्शित करने का जोखिम।
|
||||
**कोई एम्बेडिंग कैशिंग नहीं:** आवश्यक नहीं है - एम्बेडिंग पहले से ही प्रति-क्वेरी कैश किए गए हैं।
|
||||
**कोई परिणाम कैशिंग नहीं:** हटाए गए एंटिटीज/रिलेशनशिप से पुराने सबग्राफ परिणामों को रोकता है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**शमन रणनीतियाँ:**
|
||||
**रूढ़िवादी TTL मान:** प्रदर्शन लाभ (10-20%) को डेटा की ताजगी के साथ संतुलित करें।
|
||||
**कैश अमान्यकरण हुक:** ग्राफ उत्परिवर्तन घटनाओं के साथ वैकल्पिक एकीकरण।
|
||||
**निगरानी डैशबोर्ड:** कैश हिट दरों बनाम स्टेलनेस घटनाओं को ट्रैक करें।
|
||||
**कॉन्फ़िगर करने योग्य कैश नीतियां:** उत्परिवर्तन आवृत्ति के आधार पर प्रति-तैनाती ट्यूनिंग की अनुमति दें।
|
||||
|
||||
<<<<<<< HEAD
|
||||
**ग्राफ उत्परिवर्तन दर द्वारा अनुशंसित कैश कॉन्फ़िगरेशन:**
|
||||
=======
|
||||
**अनुशंसित कैश कॉन्फ़िगरेशन ग्राफ उत्परिवर्तन दर द्वारा:**
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**उच्च उत्परिवर्तन (>100 परिवर्तन/घंटा):** TTL=60s, छोटे कैश आकार।
|
||||
**मध्यम उत्परिवर्तन (10-100 परिवर्तन/घंटा):** TTL=300s (डिफ़ॉल्ट)।
|
||||
**कम उत्परिवर्तन (<10 परिवर्तन/घंटा):** TTL=600s, बड़े कैश आकार।
|
||||
|
||||
## सुरक्षा संबंधी विचार
|
||||
|
||||
**क्वेरी इंजेक्शन रोकथाम:**
|
||||
सभी एंटिटी पहचानकर्ताओं और क्वेरी मापदंडों को मान्य करें।
|
||||
सभी डेटाबेस इंटरैक्शन के लिए पैरामीटराइज़्ड क्वेरी का उपयोग करें।
|
||||
DoS हमलों को रोकने के लिए क्वेरी जटिलता सीमाएं लागू करें।
|
||||
|
||||
<<<<<<< HEAD
|
||||
**संसाधन सुरक्षा:**
|
||||
=======
|
||||
**संसाधन संरक्षण:**
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
अधिकतम सबग्राफ आकार सीमाओं को लागू करें।
|
||||
संसाधन समाप्त होने से रोकने के लिए क्वेरी टाइमआउट लागू करें।
|
||||
मेमोरी उपयोग निगरानी और सीमाएं जोड़ें।
|
||||
|
||||
**पहुंच नियंत्रण:**
|
||||
मौजूदा उपयोगकर्ता और संग्रह अलगाव बनाए रखें।
|
||||
<<<<<<< HEAD
|
||||
प्रदर्शन-प्रभावित करने वाले कार्यों के लिए ऑडिट लॉगिंग जोड़ें।
|
||||
महंगे कार्यों के लिए दर सीमित करना लागू करें।
|
||||
=======
|
||||
प्रदर्शन-प्रभावित संचालन के लिए ऑडिट लॉगिंग जोड़ें।
|
||||
महंगे संचालन के लिए दर सीमित करना लागू करें।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## प्रदर्शन संबंधी विचार
|
||||
|
||||
### अपेक्षित प्रदर्शन सुधार
|
||||
|
||||
**क्वेरी में कमी:**
|
||||
<<<<<<< HEAD
|
||||
वर्तमान: विशिष्ट अनुरोध के लिए ~9,000+ क्वेरी
|
||||
अनुकूलित: ~50-100 बैच क्वेरी (98% कमी)
|
||||
|
||||
**प्रतिक्रिया समय में सुधार:**
|
||||
ग्राफ ट्रैवर्सल: 15-20s → 3-5s (4-5x तेज़)
|
||||
लेबल रिज़ॉल्यूशन: 8-12s → 2-4s (3x तेज़)
|
||||
कुल क्वेरी: 25-35s → 6-10s (3-4x सुधार)
|
||||
|
||||
**मेमोरी दक्षता:**
|
||||
बाउंडेड कैश आकार मेमोरी लीक को रोकते हैं।
|
||||
=======
|
||||
वर्तमान: विशिष्ट अनुरोध के लिए ~9,000+ क्वेरी।
|
||||
अनुकूलित: ~50-100 बैच क्वेरी (98% कमी)।
|
||||
|
||||
**प्रतिक्रिया समय में सुधार:**
|
||||
ग्राफ ट्रैवर्सल: 15-20s → 3-5s (4-5x तेज़)।
|
||||
लेबल रिज़ॉल्यूशन: 8-12s → 2-4s (3x तेज़)।
|
||||
कुल क्वेरी: 25-35s → 6-10s (3-4x सुधार)।
|
||||
|
||||
**मेमोरी दक्षता:**
|
||||
बंधी हुई कैश आकार मेमोरी लीक को रोकते हैं।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
कुशल डेटा संरचनाएं मेमोरी पदचिह्न को ~40% तक कम करती हैं।
|
||||
उचित संसाधन सफाई के माध्यम से बेहतर कचरा संग्रह।
|
||||
|
||||
**यथार्थवादी प्रदर्शन अपेक्षाएं:**
|
||||
**लेबल कैश:** सामान्य संबंधों वाले ग्राफ़ के लिए 10-20% क्वेरी में कमी।
|
||||
**बैचिंग अनुकूलन:** 50-80% क्वेरी में कमी (प्राथमिक अनुकूलन)।
|
||||
**ऑब्जेक्ट लाइफटाइम अनुकूलन:** प्रति-अनुरोध निर्माण ओवरहेड को समाप्त करें।
|
||||
**कुल सुधार:** बैचिंग से मुख्य रूप से 3-4x प्रतिक्रिया समय में सुधार।
|
||||
|
||||
**स्केलेबिलिटी में सुधार:**
|
||||
3-5x बड़े नॉलेज ग्राफ़ के लिए समर्थन (कैश कंसिस्टेंसी आवश्यकताओं द्वारा सीमित)।
|
||||
3-5x उच्च समवर्ती अनुरोध क्षमता।
|
||||
कनेक्शन पुन: उपयोग के माध्यम से बेहतर संसाधन उपयोग।
|
||||
|
||||
### प्रदर्शन निगरानी
|
||||
|
||||
**रियल-टाइम मेट्रिक्स:**
|
||||
ऑपरेशन प्रकार द्वारा क्वेरी निष्पादन समय।
|
||||
कैश हिट अनुपात और प्रभावशीलता।
|
||||
डेटाबेस कनेक्शन पूल उपयोग।
|
||||
मेमोरी उपयोग और कचरा संग्रह प्रभाव।
|
||||
|
||||
**प्रदर्शन बेंचमार्किंग:**
|
||||
स्वचालित प्रदर्शन प्रतिगमन परीक्षण
|
||||
वास्तविक डेटा वॉल्यूम के साथ लोड परीक्षण
|
||||
वर्तमान कार्यान्वयन के खिलाफ तुलना बेंचमार्क
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
### यूनिट परीक्षण
|
||||
ट्रैवर्सल, कैशिंग और लेबल रिज़ॉल्यूशन के लिए व्यक्तिगत घटक परीक्षण
|
||||
प्रदर्शन परीक्षण के लिए मॉक डेटाबेस इंटरैक्शन
|
||||
कैश निष्कासन और TTL समाप्ति परीक्षण
|
||||
त्रुटि हैंडलिंग और टाइमआउट परिदृश्य
|
||||
|
||||
### एकीकरण परीक्षण
|
||||
अनुकूलन के साथ एंड-टू-एंड GraphRAG क्वेरी परीक्षण
|
||||
वास्तविक डेटा के साथ डेटाबेस इंटरैक्शन परीक्षण
|
||||
समवर्ती अनुरोध हैंडलिंग और संसाधन प्रबंधन
|
||||
मेमोरी लीक का पता लगाना और संसाधन सफाई सत्यापन
|
||||
|
||||
### प्रदर्शन परीक्षण
|
||||
वर्तमान कार्यान्वयन के खिलाफ बेंचमार्क परीक्षण
|
||||
विभिन्न ग्राफ आकारों और जटिलताओं के साथ लोड परीक्षण
|
||||
मेमोरी और कनेक्शन सीमाओं के लिए तनाव परीक्षण
|
||||
प्रदर्शन सुधारों के लिए प्रतिगमन परीक्षण
|
||||
|
||||
### अनुकूलता परीक्षण
|
||||
मौजूदा GraphRAG API संगतता सत्यापित करें
|
||||
विभिन्न ग्राफ डेटाबेस बैकएंड के साथ परीक्षण करें
|
||||
वर्तमान कार्यान्वयन की तुलना में परिणाम सटीकता को मान्य करें
|
||||
|
||||
## कार्यान्वयन योजना
|
||||
|
||||
### प्रत्यक्ष कार्यान्वयन दृष्टिकोण
|
||||
<<<<<<< HEAD
|
||||
चूंकि API में परिवर्तन की अनुमति है, इसलिए माइग्रेशन जटिलता के बिना अनुकूलन को सीधे लागू करें:
|
||||
=======
|
||||
चूंकि एपीआई में बदलाव की अनुमति है, इसलिए माइग्रेशन जटिलता के बिना अनुकूलन को सीधे लागू करें:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
1. **`follow_edges` विधि को बदलें**: पुनरावृत्त बैच ट्रैवर्सल के साथ फिर से लिखें
|
||||
2. **`get_labelgraph` को अनुकूलित करें**: समानांतर लेबल रिज़ॉल्यूशन लागू करें
|
||||
3. **लंबे समय तक चलने वाला GraphRag जोड़ें**: प्रोसेसर को एक स्थायी उदाहरण बनाए रखने के लिए संशोधित करें
|
||||
4. **लेबल कैशिंग लागू करें**: GraphRag क्लास में LRU कैश और TTL जोड़ें
|
||||
|
||||
### परिवर्तनों का दायरा
|
||||
**क्वेरी क्लास**: `follow_edges` में ~50 पंक्तियों को बदलें, बैच हैंडलिंग के लिए ~30 पंक्तियाँ जोड़ें
|
||||
**GraphRag क्लास**: एक कैशिंग परत जोड़ें (~40 पंक्तियाँ)
|
||||
**प्रोसेसर क्लास**: एक स्थायी GraphRag उदाहरण का उपयोग करने के लिए संशोधित करें (~20 पंक्तियाँ)
|
||||
**कुल**: केंद्रित परिवर्तनों की ~140 पंक्तियाँ, ज्यादातर मौजूदा कक्षाओं के भीतर
|
||||
|
||||
## समयरेखा
|
||||
|
||||
**सप्ताह 1: मुख्य कार्यान्वयन**
|
||||
बैच पुनरावृत्त ट्रैवर्सल के साथ `follow_edges` को बदलें
|
||||
`get_labelgraph` में समानांतर लेबल रिज़ॉल्यूशन लागू करें
|
||||
प्रोसेसर में एक लंबे समय तक चलने वाला GraphRag उदाहरण जोड़ें
|
||||
एक लेबल कैशिंग परत लागू करें
|
||||
|
||||
**सप्ताह 2: परीक्षण और एकीकरण**
|
||||
<<<<<<< HEAD
|
||||
नए ट्रैवर्सल और कैशिंग तर्क के लिए यूनिट परीक्षण
|
||||
=======
|
||||
नए ट्रैवर्सल और कैशिंग लॉजिक के लिए यूनिट परीक्षण
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
वर्तमान कार्यान्वयन के खिलाफ प्रदर्शन बेंचमार्किंग
|
||||
वास्तविक ग्राफ डेटा के साथ एकीकरण परीक्षण
|
||||
कोड समीक्षा और अनुकूलन
|
||||
|
||||
**सप्ताह 3: परिनियोजन**
|
||||
अनुकूलित कार्यान्वयन को तैनात करें
|
||||
प्रदर्शन सुधारों की निगरानी करें
|
||||
वास्तविक उपयोग के आधार पर कैश TTL और बैच आकारों को ठीक करें
|
||||
|
||||
## खुले प्रश्न
|
||||
|
||||
**डेटाबेस कनेक्शन पूलिंग**: क्या हमें कस्टम कनेक्शन पूलिंग लागू करनी चाहिए या मौजूदा डेटाबेस क्लाइंट पूलिंग पर भरोसा करना चाहिए?
|
||||
<<<<<<< HEAD
|
||||
**कैश दृढ़ता**: क्या लेबल और एम्बेडिंग कैश सेवा पुनरारंभों में बने रहने चाहिए?
|
||||
=======
|
||||
**कैश दृढ़ता**: क्या लेबल और एम्बेडिंग कैश सेवा पुनरारंभों में बने रहेंगे?
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**वितरित कैशिंग**: मल्टी-इंस्टेंस परिनियोजन के लिए, क्या हमें Redis/Memcached के साथ वितरित कैशिंग लागू करनी चाहिए?
|
||||
**क्वेरी परिणाम प्रारूप**: क्या हमें बेहतर मेमोरी दक्षता के लिए आंतरिक ट्रिपल प्रतिनिधित्व को अनुकूलित करना चाहिए?
|
||||
**निगरानी एकीकरण**: मौजूदा निगरानी प्रणालियों (Prometheus, आदि) के लिए कौन से मेट्रिक्स उजागर किए जाने चाहिए?
|
||||
|
||||
## संदर्भ
|
||||
|
||||
[GraphRAG मूल कार्यान्वयन](trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py)
|
||||
[ट्रस्टग्राफ आर्किटेक्चर सिद्धांत](architecture-principles.md)
|
||||
[संग्रह प्रबंधन विनिर्देश](collection-management.md)
|
||||
718
docs/tech-specs/hi/import-export-graceful-shutdown.hi.md
Normal file
718
docs/tech-specs/hi/import-export-graceful-shutdown.hi.md
Normal file
|
|
@ -0,0 +1,718 @@
|
|||
---
|
||||
layout: default
|
||||
title: "आयात/निर्यात के लिए सुचारू शटडाउन तकनीकी विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# आयात/निर्यात के लिए सुचारू शटडाउन तकनीकी विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
## समस्या विवरण
|
||||
|
||||
<<<<<<< HEAD
|
||||
ट्रस्टग्राफ गेटवे वर्तमान में आयात और निर्यात दोनों कार्यों के दौरान वेबसॉकेट बंद होने के समय संदेश हानि का अनुभव करता है। यह दौड़ की स्थितियों के कारण होता है जहां पारगमन में मौजूद संदेश अपने गंतव्य (आयात के लिए पल्सर कतारों, निर्यात के लिए वेबसॉकेट क्लाइंट) तक पहुंचने से पहले त्याग दिए जाते हैं।
|
||||
=======
|
||||
ट्रस्टग्राफ गेटवे वर्तमान में आयात और निर्यात दोनों कार्यों के दौरान वेबसॉकेट बंद होने के समय संदेशों के खो जाने की समस्या का सामना करता है। यह दौड़ की स्थितियों के कारण होता है, जिसमें रास्ते में मौजूद संदेशों को उनके गंतव्य (आयात के लिए पल्सर कतारों, निर्यात के लिए वेबसॉकेट क्लाइंट) तक पहुंचने से पहले त्याग दिया जाता है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
### आयात-पक्ष की समस्याएं
|
||||
1. प्रकाशक का asyncio.Queue बफर शटडाउन पर खाली नहीं होता है।
|
||||
2. वेबसॉकेट बंद होने से पहले यह सुनिश्चित नहीं किया जाता है कि कतारबद्ध संदेश पल्सर तक पहुंचें।
|
||||
3. सफल संदेश वितरण के लिए कोई स्वीकृति तंत्र नहीं है।
|
||||
|
||||
### निर्यात-पक्ष की समस्याएं
|
||||
1. संदेशों को क्लाइंट को सफलतापूर्वक वितरित होने से पहले पल्सर में स्वीकार किया जाता है।
|
||||
2. हार्ड-कोडेड टाइमआउट के कारण संदेश ड्रॉप हो जाते हैं जब कतारें भरी होती हैं।
|
||||
3. धीमी उपभोक्ताओं को संभालने के लिए कोई बैकप्रेशर तंत्र नहीं है।
|
||||
<<<<<<< HEAD
|
||||
4. कई बफर बिंदु जहां डेटा खो सकता है।
|
||||
=======
|
||||
4. कई बफर बिंदु हैं जहां डेटा खो सकता है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## वास्तुकला अवलोकन
|
||||
|
||||
```
|
||||
Import Flow:
|
||||
Client -> Websocket -> TriplesImport -> Publisher -> Pulsar Queue
|
||||
|
||||
Export Flow:
|
||||
Pulsar Queue -> Subscriber -> TriplesExport -> Websocket -> Client
|
||||
```
|
||||
|
||||
## प्रस्तावित सुधार
|
||||
|
||||
### 1. प्रकाशक में सुधार (आयात पक्ष)
|
||||
|
||||
#### ए. सुचारू कतार खाली करना
|
||||
|
||||
**फ़ाइल**: `trustgraph-base/trustgraph/base/publisher.py`
|
||||
|
||||
```python
|
||||
class Publisher:
|
||||
def __init__(self, client, topic, schema=None, max_size=10,
|
||||
chunking_enabled=True, drain_timeout=5.0):
|
||||
self.client = client
|
||||
self.topic = topic
|
||||
self.schema = schema
|
||||
self.q = asyncio.Queue(maxsize=max_size)
|
||||
self.chunking_enabled = chunking_enabled
|
||||
self.running = True
|
||||
self.draining = False # New state for graceful shutdown
|
||||
self.task = None
|
||||
self.drain_timeout = drain_timeout
|
||||
|
||||
async def stop(self):
|
||||
"""Initiate graceful shutdown with draining"""
|
||||
self.running = False
|
||||
self.draining = True
|
||||
|
||||
if self.task:
|
||||
# Wait for run() to complete draining
|
||||
await self.task
|
||||
|
||||
async def run(self):
|
||||
"""Enhanced run method with integrated draining logic"""
|
||||
while self.running or self.draining:
|
||||
try:
|
||||
producer = self.client.create_producer(
|
||||
topic=self.topic,
|
||||
schema=JsonSchema(self.schema),
|
||||
chunking_enabled=self.chunking_enabled,
|
||||
)
|
||||
|
||||
drain_end_time = None
|
||||
|
||||
while self.running or self.draining:
|
||||
try:
|
||||
# Start drain timeout when entering drain mode
|
||||
if self.draining and drain_end_time is None:
|
||||
drain_end_time = time.time() + self.drain_timeout
|
||||
logger.info(f"Publisher entering drain mode, timeout={self.drain_timeout}s")
|
||||
|
||||
# Check drain timeout
|
||||
if self.draining and time.time() > drain_end_time:
|
||||
if not self.q.empty():
|
||||
logger.warning(f"Drain timeout reached with {self.q.qsize()} messages remaining")
|
||||
self.draining = False
|
||||
break
|
||||
|
||||
# Calculate wait timeout based on mode
|
||||
if self.draining:
|
||||
# Shorter timeout during draining to exit quickly when empty
|
||||
timeout = min(0.1, drain_end_time - time.time())
|
||||
else:
|
||||
# Normal operation timeout
|
||||
timeout = 0.25
|
||||
|
||||
# Get message from queue
|
||||
id, item = await asyncio.wait_for(
|
||||
self.q.get(),
|
||||
timeout=timeout
|
||||
)
|
||||
|
||||
# Send the message (single place for sending)
|
||||
if id:
|
||||
producer.send(item, { "id": id })
|
||||
else:
|
||||
producer.send(item)
|
||||
|
||||
except asyncio.TimeoutError:
|
||||
# If draining and queue is empty, we're done
|
||||
if self.draining and self.q.empty():
|
||||
logger.info("Publisher queue drained successfully")
|
||||
self.draining = False
|
||||
break
|
||||
continue
|
||||
|
||||
except asyncio.QueueEmpty:
|
||||
# If draining and queue is empty, we're done
|
||||
if self.draining and self.q.empty():
|
||||
logger.info("Publisher queue drained successfully")
|
||||
self.draining = False
|
||||
break
|
||||
continue
|
||||
|
||||
# Flush producer before closing
|
||||
if producer:
|
||||
producer.flush()
|
||||
producer.close()
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Exception in publisher: {e}", exc_info=True)
|
||||
|
||||
if not self.running and not self.draining:
|
||||
return
|
||||
|
||||
# If handler drops out, sleep a retry
|
||||
await asyncio.sleep(1)
|
||||
|
||||
async def send(self, id, item):
|
||||
"""Send still works normally - just adds to queue"""
|
||||
if self.draining:
|
||||
# Optionally reject new messages during drain
|
||||
raise RuntimeError("Publisher is shutting down, not accepting new messages")
|
||||
await self.q.put((id, item))
|
||||
```
|
||||
|
||||
**मुख्य डिज़ाइन लाभ:**
|
||||
**एकल प्रेषण स्थान**: सभी `producer.send()` कॉल `run()` विधि के भीतर एक ही स्थान पर होते हैं।
|
||||
**स्वच्छ स्टेट मशीन**: तीन स्पष्ट अवस्थाएँ - चल रही, खाली करने की प्रक्रिया में, बंद।
|
||||
**टाइमआउट सुरक्षा**: खाली करने के दौरान अनिश्चित काल तक नहीं रुकेगा।
|
||||
**बेहतर अवलोकन क्षमता**: खाली करने की प्रगति और अवस्था परिवर्तनों का स्पष्ट लॉगिंग।
|
||||
**वैकल्पिक संदेश अस्वीकृति**: शटडाउन चरण के दौरान नए संदेशों को अस्वीकार किया जा सकता है।
|
||||
|
||||
#### बी. बेहतर शटडाउन क्रम
|
||||
|
||||
**फ़ाइल**: `trustgraph-flow/trustgraph/gateway/dispatch/triples_import.py`
|
||||
|
||||
```python
|
||||
class TriplesImport:
|
||||
async def destroy(self):
|
||||
"""Enhanced destroy with proper shutdown order"""
|
||||
# Step 1: Stop accepting new messages
|
||||
self.running.stop()
|
||||
|
||||
# Step 2: Wait for publisher to drain its queue
|
||||
logger.info("Draining publisher queue...")
|
||||
await self.publisher.stop()
|
||||
|
||||
# Step 3: Close websocket only after queue is drained
|
||||
if self.ws:
|
||||
await self.ws.close()
|
||||
```
|
||||
|
||||
### 2. ग्राहक सुधार (निर्यात पक्ष)
|
||||
|
||||
#### ए. एकीकृत जल निकासी पैटर्न
|
||||
|
||||
**फ़ाइल**: `trustgraph-base/trustgraph/base/subscriber.py`
|
||||
|
||||
```python
|
||||
class Subscriber:
|
||||
def __init__(self, client, topic, subscription, consumer_name,
|
||||
schema=None, max_size=100, metrics=None,
|
||||
backpressure_strategy="block", drain_timeout=5.0):
|
||||
# ... existing init ...
|
||||
self.backpressure_strategy = backpressure_strategy
|
||||
self.running = True
|
||||
self.draining = False # New state for graceful shutdown
|
||||
self.drain_timeout = drain_timeout
|
||||
self.pending_acks = {} # Track messages awaiting delivery
|
||||
|
||||
async def stop(self):
|
||||
"""Initiate graceful shutdown with draining"""
|
||||
self.running = False
|
||||
self.draining = True
|
||||
|
||||
if self.task:
|
||||
# Wait for run() to complete draining
|
||||
await self.task
|
||||
|
||||
async def run(self):
|
||||
"""Enhanced run method with integrated draining logic"""
|
||||
while self.running or self.draining:
|
||||
if self.metrics:
|
||||
self.metrics.state("stopped")
|
||||
|
||||
try:
|
||||
self.consumer = self.client.subscribe(
|
||||
topic = self.topic,
|
||||
subscription_name = self.subscription,
|
||||
consumer_name = self.consumer_name,
|
||||
schema = JsonSchema(self.schema),
|
||||
)
|
||||
|
||||
if self.metrics:
|
||||
self.metrics.state("running")
|
||||
|
||||
logger.info("Subscriber running...")
|
||||
drain_end_time = None
|
||||
|
||||
while self.running or self.draining:
|
||||
# Start drain timeout when entering drain mode
|
||||
if self.draining and drain_end_time is None:
|
||||
drain_end_time = time.time() + self.drain_timeout
|
||||
logger.info(f"Subscriber entering drain mode, timeout={self.drain_timeout}s")
|
||||
|
||||
# Stop accepting new messages from Pulsar during drain
|
||||
self.consumer.pause_message_listener()
|
||||
|
||||
# Check drain timeout
|
||||
if self.draining and time.time() > drain_end_time:
|
||||
async with self.lock:
|
||||
total_pending = sum(
|
||||
q.qsize() for q in
|
||||
list(self.q.values()) + list(self.full.values())
|
||||
)
|
||||
if total_pending > 0:
|
||||
logger.warning(f"Drain timeout reached with {total_pending} messages in queues")
|
||||
self.draining = False
|
||||
break
|
||||
|
||||
# Check if we can exit drain mode
|
||||
if self.draining:
|
||||
async with self.lock:
|
||||
all_empty = all(
|
||||
q.empty() for q in
|
||||
list(self.q.values()) + list(self.full.values())
|
||||
)
|
||||
if all_empty and len(self.pending_acks) == 0:
|
||||
logger.info("Subscriber queues drained successfully")
|
||||
self.draining = False
|
||||
break
|
||||
|
||||
# Process messages only if not draining
|
||||
if not self.draining:
|
||||
try:
|
||||
msg = await asyncio.to_thread(
|
||||
self.consumer.receive,
|
||||
timeout_millis=250
|
||||
)
|
||||
except _pulsar.Timeout:
|
||||
continue
|
||||
except Exception as e:
|
||||
logger.error(f"Exception in subscriber receive: {e}", exc_info=True)
|
||||
raise e
|
||||
|
||||
if self.metrics:
|
||||
self.metrics.received()
|
||||
|
||||
# Process the message
|
||||
await self._process_message(msg)
|
||||
else:
|
||||
# During draining, just wait for queues to empty
|
||||
await asyncio.sleep(0.1)
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Subscriber exception: {e}", exc_info=True)
|
||||
|
||||
finally:
|
||||
# Negative acknowledge any pending messages
|
||||
for msg in self.pending_acks.values():
|
||||
self.consumer.negative_acknowledge(msg)
|
||||
self.pending_acks.clear()
|
||||
|
||||
if self.consumer:
|
||||
self.consumer.unsubscribe()
|
||||
self.consumer.close()
|
||||
self.consumer = None
|
||||
|
||||
if self.metrics:
|
||||
self.metrics.state("stopped")
|
||||
|
||||
if not self.running and not self.draining:
|
||||
return
|
||||
|
||||
# If handler drops out, sleep a retry
|
||||
await asyncio.sleep(1)
|
||||
|
||||
async def _process_message(self, msg):
|
||||
"""Process a single message with deferred acknowledgment"""
|
||||
# Store message for later acknowledgment
|
||||
msg_id = str(uuid.uuid4())
|
||||
self.pending_acks[msg_id] = msg
|
||||
|
||||
try:
|
||||
id = msg.properties()["id"]
|
||||
except:
|
||||
id = None
|
||||
|
||||
value = msg.value()
|
||||
delivery_success = False
|
||||
|
||||
async with self.lock:
|
||||
# Deliver to specific subscribers
|
||||
if id in self.q:
|
||||
delivery_success = await self._deliver_to_queue(
|
||||
self.q[id], value
|
||||
)
|
||||
|
||||
# Deliver to all subscribers
|
||||
for q in self.full.values():
|
||||
if await self._deliver_to_queue(q, value):
|
||||
delivery_success = True
|
||||
|
||||
# Acknowledge only on successful delivery
|
||||
if delivery_success:
|
||||
self.consumer.acknowledge(msg)
|
||||
del self.pending_acks[msg_id]
|
||||
else:
|
||||
# Negative acknowledge for retry
|
||||
self.consumer.negative_acknowledge(msg)
|
||||
del self.pending_acks[msg_id]
|
||||
|
||||
async def _deliver_to_queue(self, queue, value):
|
||||
"""Deliver message to queue with backpressure handling"""
|
||||
try:
|
||||
if self.backpressure_strategy == "block":
|
||||
# Block until space available (no timeout)
|
||||
await queue.put(value)
|
||||
return True
|
||||
|
||||
elif self.backpressure_strategy == "drop_oldest":
|
||||
# Drop oldest message if queue full
|
||||
if queue.full():
|
||||
try:
|
||||
queue.get_nowait()
|
||||
if self.metrics:
|
||||
self.metrics.dropped()
|
||||
except asyncio.QueueEmpty:
|
||||
pass
|
||||
await queue.put(value)
|
||||
return True
|
||||
|
||||
elif self.backpressure_strategy == "drop_new":
|
||||
# Drop new message if queue full
|
||||
if queue.full():
|
||||
if self.metrics:
|
||||
self.metrics.dropped()
|
||||
return False
|
||||
await queue.put(value)
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to deliver message: {e}")
|
||||
return False
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
**मुख्य डिज़ाइन लाभ (प्रकाशक पैटर्न से मेल खाता):**
|
||||
=======
|
||||
**मुख्य डिज़ाइन लाभ (प्रकाशक पैटर्न से मेल खाता है):**
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**एकल प्रसंस्करण स्थान**: सभी संदेश प्रसंस्करण `run()` विधि में होता है।
|
||||
**स्वच्छ स्टेट मशीन**: तीन स्पष्ट अवस्थाएँ - चल रही, खाली करने की प्रक्रिया में, बंद।
|
||||
**खाली करते समय विराम**: मौजूदा कतारों को खाली करते समय, पल्सर से नए संदेश स्वीकार करना बंद हो जाता है।
|
||||
**समय-सीमा सुरक्षा**: खाली करने की प्रक्रिया के दौरान अनिश्चित काल तक नहीं रुकेगा।
|
||||
<<<<<<< HEAD
|
||||
**उचित सफाई**: शटडाउन पर, किसी भी अप्राप्त संदेश को नकारात्मक रूप से स्वीकार किया जाता है।
|
||||
=======
|
||||
**उचित सफाई**: शटडाउन पर किसी भी अप्राप्त संदेश को नकारात्मक रूप से स्वीकार करता है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
#### बी. एक्सपोर्ट हैंडलर में सुधार
|
||||
|
||||
**फ़ाइल**: `trustgraph-flow/trustgraph/gateway/dispatch/triples_export.py`
|
||||
|
||||
```python
|
||||
class TriplesExport:
|
||||
async def destroy(self):
|
||||
"""Enhanced destroy with graceful shutdown"""
|
||||
# Step 1: Signal stop to prevent new messages
|
||||
self.running.stop()
|
||||
|
||||
# Step 2: Wait briefly for in-flight messages
|
||||
await asyncio.sleep(0.5)
|
||||
|
||||
# Step 3: Unsubscribe and stop subscriber (triggers queue drain)
|
||||
if hasattr(self, 'subs'):
|
||||
await self.subs.unsubscribe_all(self.id)
|
||||
await self.subs.stop()
|
||||
|
||||
# Step 4: Close websocket last
|
||||
if self.ws and not self.ws.closed:
|
||||
await self.ws.close()
|
||||
|
||||
async def run(self):
|
||||
"""Enhanced run with better error handling"""
|
||||
self.subs = Subscriber(
|
||||
client = self.pulsar_client,
|
||||
topic = self.queue,
|
||||
consumer_name = self.consumer,
|
||||
subscription = self.subscriber,
|
||||
schema = Triples,
|
||||
backpressure_strategy = "block" # Configurable
|
||||
)
|
||||
|
||||
await self.subs.start()
|
||||
|
||||
self.id = str(uuid.uuid4())
|
||||
q = await self.subs.subscribe_all(self.id)
|
||||
|
||||
consecutive_errors = 0
|
||||
max_consecutive_errors = 5
|
||||
|
||||
while self.running.get():
|
||||
try:
|
||||
resp = await asyncio.wait_for(q.get(), timeout=0.5)
|
||||
await self.ws.send_json(serialize_triples(resp))
|
||||
consecutive_errors = 0 # Reset on success
|
||||
|
||||
except asyncio.TimeoutError:
|
||||
continue
|
||||
|
||||
except queue.Empty:
|
||||
continue
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Exception sending to websocket: {str(e)}")
|
||||
consecutive_errors += 1
|
||||
|
||||
if consecutive_errors >= max_consecutive_errors:
|
||||
logger.error("Too many consecutive errors, shutting down")
|
||||
break
|
||||
|
||||
# Brief pause before retry
|
||||
await asyncio.sleep(0.1)
|
||||
|
||||
# Graceful cleanup handled in destroy()
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
### 3. सॉकेट-स्तरीय सुधार
|
||||
=======
|
||||
### 3. सॉकेट-स्तर में सुधार
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**फ़ाइल**: `trustgraph-flow/trustgraph/gateway/endpoint/socket.py`
|
||||
|
||||
```python
|
||||
class SocketEndpoint:
|
||||
async def listener(self, ws, dispatcher, running):
|
||||
"""Enhanced listener with graceful shutdown"""
|
||||
async for msg in ws:
|
||||
if msg.type == WSMsgType.TEXT:
|
||||
await dispatcher.receive(msg)
|
||||
continue
|
||||
elif msg.type == WSMsgType.BINARY:
|
||||
await dispatcher.receive(msg)
|
||||
continue
|
||||
else:
|
||||
# Graceful shutdown on close
|
||||
logger.info("Websocket closing, initiating graceful shutdown")
|
||||
running.stop()
|
||||
|
||||
# Allow time for dispatcher cleanup
|
||||
await asyncio.sleep(1.0)
|
||||
break
|
||||
|
||||
async def handle(self, request):
|
||||
"""Enhanced handler with better cleanup"""
|
||||
# ... existing setup code ...
|
||||
|
||||
try:
|
||||
async with asyncio.TaskGroup() as tg:
|
||||
running = Running()
|
||||
|
||||
dispatcher = await self.dispatcher(
|
||||
ws, running, request.match_info
|
||||
)
|
||||
|
||||
worker_task = tg.create_task(
|
||||
self.worker(ws, dispatcher, running)
|
||||
)
|
||||
|
||||
lsnr_task = tg.create_task(
|
||||
self.listener(ws, dispatcher, running)
|
||||
)
|
||||
|
||||
except ExceptionGroup as e:
|
||||
logger.error("Exception group occurred:", exc_info=True)
|
||||
|
||||
# Attempt graceful dispatcher shutdown
|
||||
try:
|
||||
await asyncio.wait_for(
|
||||
dispatcher.destroy(),
|
||||
timeout=5.0
|
||||
)
|
||||
except asyncio.TimeoutError:
|
||||
logger.warning("Dispatcher shutdown timed out")
|
||||
except Exception as de:
|
||||
logger.error(f"Error during dispatcher cleanup: {de}")
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Socket exception: {e}", exc_info=True)
|
||||
|
||||
finally:
|
||||
# Ensure dispatcher cleanup
|
||||
if dispatcher and hasattr(dispatcher, 'destroy'):
|
||||
try:
|
||||
await dispatcher.destroy()
|
||||
except:
|
||||
pass
|
||||
|
||||
# Ensure websocket is closed
|
||||
if ws and not ws.closed:
|
||||
await ws.close()
|
||||
|
||||
return ws
|
||||
```
|
||||
|
||||
## कॉन्फ़िगरेशन विकल्प
|
||||
|
||||
व्यवहार को अनुकूलित करने के लिए कॉन्फ़िगरेशन समर्थन जोड़ें:
|
||||
|
||||
```python
|
||||
# config.py
|
||||
class GracefulShutdownConfig:
|
||||
# Publisher settings
|
||||
PUBLISHER_DRAIN_TIMEOUT = 5.0 # Seconds to wait for queue drain
|
||||
PUBLISHER_FLUSH_TIMEOUT = 2.0 # Producer flush timeout
|
||||
|
||||
# Subscriber settings
|
||||
SUBSCRIBER_DRAIN_TIMEOUT = 5.0 # Seconds to wait for queue drain
|
||||
BACKPRESSURE_STRATEGY = "block" # Options: "block", "drop_oldest", "drop_new"
|
||||
SUBSCRIBER_MAX_QUEUE_SIZE = 100 # Maximum queue size before backpressure
|
||||
|
||||
# Socket settings
|
||||
SHUTDOWN_GRACE_PERIOD = 1.0 # Seconds to wait for graceful shutdown
|
||||
MAX_CONSECUTIVE_ERRORS = 5 # Maximum errors before forced shutdown
|
||||
|
||||
# Monitoring
|
||||
LOG_QUEUE_STATS = True # Log queue statistics on shutdown
|
||||
METRICS_ENABLED = True # Enable metrics collection
|
||||
```
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
<<<<<<< HEAD
|
||||
### यूनिट परीक्षण
|
||||
=======
|
||||
### इकाई परीक्षण
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
```python
|
||||
async def test_publisher_queue_drain():
|
||||
"""Verify Publisher drains queue on shutdown"""
|
||||
publisher = Publisher(...)
|
||||
|
||||
# Fill queue with messages
|
||||
for i in range(10):
|
||||
await publisher.send(f"id-{i}", {"data": i})
|
||||
|
||||
# Stop publisher
|
||||
await publisher.stop()
|
||||
|
||||
# Verify all messages were sent
|
||||
assert publisher.q.empty()
|
||||
assert mock_producer.send.call_count == 10
|
||||
|
||||
async def test_subscriber_deferred_ack():
|
||||
"""Verify Subscriber only acks on successful delivery"""
|
||||
subscriber = Subscriber(..., backpressure_strategy="drop_new")
|
||||
|
||||
# Fill queue to capacity
|
||||
queue = await subscriber.subscribe("test")
|
||||
for i in range(100):
|
||||
await queue.put({"data": i})
|
||||
|
||||
# Try to add message when full
|
||||
msg = create_mock_message()
|
||||
await subscriber._process_message(msg)
|
||||
|
||||
# Verify negative acknowledgment
|
||||
assert msg.negative_acknowledge.called
|
||||
assert not msg.acknowledge.called
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
### एकीकरण परीक्षण (एकीकरण परीक्षण)
|
||||
=======
|
||||
### एकीकरण परीक्षण
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
```python
|
||||
async def test_import_graceful_shutdown():
|
||||
"""Test import path handles shutdown gracefully"""
|
||||
# Setup
|
||||
import_handler = TriplesImport(...)
|
||||
await import_handler.start()
|
||||
|
||||
# Send messages
|
||||
messages = []
|
||||
for i in range(100):
|
||||
msg = {"metadata": {...}, "triples": [...]}
|
||||
await import_handler.receive(msg)
|
||||
messages.append(msg)
|
||||
|
||||
# Shutdown while messages in flight
|
||||
await import_handler.destroy()
|
||||
|
||||
# Verify all messages reached Pulsar
|
||||
received = await pulsar_consumer.receive_all()
|
||||
assert len(received) == 100
|
||||
|
||||
async def test_export_no_message_loss():
|
||||
"""Test export path doesn't lose acknowledged messages"""
|
||||
# Setup Pulsar with test messages
|
||||
for i in range(100):
|
||||
await pulsar_producer.send({"data": i})
|
||||
|
||||
# Start export handler
|
||||
export_handler = TriplesExport(...)
|
||||
export_task = asyncio.create_task(export_handler.run())
|
||||
|
||||
# Receive some messages
|
||||
received = []
|
||||
for _ in range(50):
|
||||
msg = await websocket.receive()
|
||||
received.append(msg)
|
||||
|
||||
# Force shutdown
|
||||
await export_handler.destroy()
|
||||
|
||||
# Continue receiving until websocket closes
|
||||
while not websocket.closed:
|
||||
try:
|
||||
msg = await websocket.receive()
|
||||
received.append(msg)
|
||||
except:
|
||||
break
|
||||
|
||||
# Verify no acknowledged messages were lost
|
||||
assert len(received) >= 50
|
||||
```
|
||||
|
||||
## रोलआउट योजना
|
||||
|
||||
### चरण 1: महत्वपूर्ण सुधार (सप्ताह 1)
|
||||
सब्सक्राइबर स्वीकृति समय को ठीक करें (संदेश हानि को रोकें)
|
||||
पब्लिशर क्यू को खाली करने की सुविधा जोड़ें
|
||||
स्टेजिंग वातावरण में तैनात करें
|
||||
|
||||
### चरण 2: सुचारू शटडाउन (सप्ताह 2)
|
||||
शटडाउन समन्वय लागू करें
|
||||
बैकप्रेशर रणनीतियों को जोड़ें
|
||||
प्रदर्शन परीक्षण
|
||||
|
||||
### चरण 3: निगरानी और ट्यूनिंग (सप्ताह 3)
|
||||
क्यू की गहराई के लिए मेट्रिक्स जोड़ें
|
||||
संदेश ड्रॉप के लिए अलर्ट जोड़ें
|
||||
उत्पादन डेटा के आधार पर टाइमआउट मानों को ट्यून करें
|
||||
|
||||
## निगरानी और अलर्ट
|
||||
|
||||
### ट्रैक करने के लिए मेट्रिक्स
|
||||
`publisher.queue.depth` - वर्तमान पब्लिशर क्यू का आकार
|
||||
`publisher.messages.dropped` - शटडाउन के दौरान खोए गए संदेश
|
||||
`subscriber.messages.negatively_acknowledged` - विफल डिलीवरी
|
||||
`websocket.graceful_shutdowns` - सफल सुचारू शटडाउन
|
||||
`websocket.forced_shutdowns` - मजबूर/टाइमआउट शटडाउन
|
||||
|
||||
### अलर्ट
|
||||
पब्लिशर क्यू की गहराई > 80% क्षमता
|
||||
शटडाउन के दौरान कोई भी संदेश ड्रॉप
|
||||
सब्सक्राइबर नकारात्मक स्वीकृति दर > 1%
|
||||
शटडाउन टाइमआउट समाप्त
|
||||
|
||||
## पिछली अनुकूलता
|
||||
|
||||
सभी परिवर्तनों में पिछली अनुकूलता बनी हुई है:
|
||||
कॉन्फ़िगरेशन के बिना डिफ़ॉल्ट व्यवहार अपरिवर्तित रहता है
|
||||
मौजूदा डिप्लॉयमेंट सामान्य रूप से काम करना जारी रखते हैं
|
||||
यदि नई सुविधाएँ अनुपलब्ध हैं तो सुचारू गिरावट
|
||||
|
||||
## सुरक्षा संबंधी विचार
|
||||
|
||||
कोई नया आक्रमण वेक्टर नहीं जोड़ा गया
|
||||
बैकप्रेशर मेमोरी थकावट हमलों को रोकता है
|
||||
कॉन्फ़िगर करने योग्य सीमाएँ संसाधन दुरुपयोग को रोकती हैं
|
||||
|
||||
## प्रदर्शन प्रभाव
|
||||
|
||||
सामान्य संचालन के दौरान न्यूनतम ओवरहेड
|
||||
शटडाउन में 5 सेकंड तक अधिक समय लग सकता है (कॉन्फ़िगर करने योग्य)
|
||||
मेमोरी उपयोग क्यू आकार सीमाओं द्वारा सीमित है
|
||||
CPU पर प्रभाव नगण्य (<1% वृद्धि)
|
||||
561
docs/tech-specs/hi/jsonl-prompt-output.hi.md
Normal file
561
docs/tech-specs/hi/jsonl-prompt-output.hi.md
Normal file
|
|
@ -0,0 +1,561 @@
|
|||
---
|
||||
layout: default
|
||||
title: "JSONL प्रॉम्प्ट आउटपुट तकनीकी विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# JSONL प्रॉम्प्ट आउटपुट तकनीकी विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
<<<<<<< HEAD
|
||||
यह विनिर्देश ट्रस्टग्राफ में प्रॉम्प्ट प्रतिक्रियाओं के लिए JSONL (JSON लाइन्स) आउटपुट प्रारूप के कार्यान्वयन का वर्णन करता है। JSONL, LLM प्रतिक्रियाओं से संरचित डेटा को निकालने में सक्षम बनाता है, जो कि LLM प्रतिक्रियाओं के आउटपुट टोकन सीमाओं तक पहुंचने पर JSON सरणी आउटपुट के दूषित होने जैसी महत्वपूर्ण समस्याओं को हल करता है।
|
||||
|
||||
|
||||
|
||||
|
||||
=======
|
||||
यह विनिर्देश ट्रस्टग्राफ में प्रॉम्प्ट प्रतिक्रियाओं के लिए JSONL (JSON लाइन्स) आउटपुट प्रारूप के कार्यान्वयन का वर्णन करता है। JSONL, LLM प्रतिक्रियाओं से संरचित डेटा को निकालने में सक्षम बनाता है, जो कि LLM प्रतिक्रियाओं के आउटपुट टोकन सीमाओं तक पहुंचने पर JSON सरणी आउटपुट के दूषित होने जैसी महत्वपूर्ण समस्याओं का समाधान करता है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
|
||||
<<<<<<< HEAD
|
||||
1. **ट्रंकेशन-रेज़िलिएंट एक्सट्रैक्शन (Truncation-Resilient Extraction)**: वैध आंशिक परिणाम निकालें, भले ही
|
||||
एलएलएम (LLM) आउटपुट प्रतिक्रिया के बीच में ही काट दिया गया हो।
|
||||
2. **बड़े पैमाने पर एक्सट्रैक्शन (Large-Scale Extraction)**: टोकन सीमाओं के कारण पूर्ण विफलता के जोखिम के बिना, कई वस्तुओं के निष्कर्षण को संभालें।
|
||||
3. **मिश्रित-प्रकार एक्सट्रैक्शन (Mixed-Type Extraction)**: एक ही प्रॉम्प्ट में कई इकाई प्रकारों (परिभाषाओं, संबंधों, संस्थाओं, विशेषताओं) के निष्कर्षण का समर्थन करें।
|
||||
4. **स्ट्रीमिंग-संगत आउटपुट (Streaming-Compatible Output)**: निष्कर्षण परिणामों की भविष्य की स्ट्रीमिंग/क्रमिक
|
||||
प्रसंस्करण को सक्षम करें।
|
||||
|
||||
|
||||
=======
|
||||
|
||||
|
||||
|
||||
यह कार्यान्वयन निम्नलिखित उपयोग परिदृश्यों का समर्थन करता है:
|
||||
|
||||
1. **ट्रंकेशन-प्रतिरोधी निष्कर्षण**: भले ही एलएलएम आउटपुट प्रतिक्रिया के बीच में काट दिया गया हो, फिर भी मान्य आंशिक परिणाम निकालें।
|
||||
एलएलएम आउटपुट प्रतिक्रिया के बीच में काट दिया गया हो, फिर भी मान्य आंशिक परिणाम निकालें।
|
||||
2. **बड़ी-पैमाने पर निष्कर्षण**: टोकन सीमाओं के कारण पूर्ण विफलता के जोखिम के बिना, कई वस्तुओं के निष्कर्षण को संभालें।
|
||||
टोकन सीमाओं के कारण पूर्ण विफलता के जोखिम के बिना, कई वस्तुओं के निष्कर्षण को संभालें।
|
||||
3. **मिश्रित-प्रकार निष्कर्षण**: एक ही प्रॉम्प्ट में कई इकाई प्रकारों (परिभाषाएँ, संबंध, इकाइयाँ, विशेषताएँ) के निष्कर्षण का समर्थन करें।
|
||||
एक ही प्रॉम्प्ट में कई इकाई प्रकारों (परिभाषाएँ, संबंध, इकाइयाँ, विशेषताएँ) के निष्कर्षण का समर्थन करें।
|
||||
4. **स्ट्रीमिंग-संगत आउटपुट**: निष्कर्षण परिणामों की भविष्य की स्ट्रीमिंग/क्रमिक प्रसंस्करण को सक्षम करें।
|
||||
निष्कर्षण परिणामों की भविष्य की स्ट्रीमिंग/क्रमिक प्रसंस्करण को सक्षम करें।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
**पिछड़ा संगतता (Backward Compatibility)**: मौजूदा प्रॉम्प्ट जो `response-type: "text"` और का उपयोग करते हैं,
|
||||
<<<<<<< HEAD
|
||||
`response-type: "json"` बिना किसी बदलाव के काम करना जारी रखते हैं।
|
||||
**अतिसंयमी लचीलापन (Truncation Resilience)**: आंशिक एलएलएम आउटपुट आंशिक, मान्य परिणाम देते हैं,
|
||||
पूर्ण विफलता के बजाय।
|
||||
**स्कीमा सत्यापन (Schema Validation)**: व्यक्तिगत ऑब्जेक्ट के लिए JSON स्कीमा सत्यापन का समर्थन।
|
||||
=======
|
||||
`response-type: "json"`, बिना किसी बदलाव के काम करना जारी रखते हैं।
|
||||
**अतिसंयमी लचीलापन (Truncation Resilience)**: आंशिक एलएलएम आउटपुट आंशिक, मान्य परिणाम देते हैं,
|
||||
पूर्ण विफलता के बजाय।
|
||||
**स्कीमा सत्यापन (Schema Validation)**: व्यक्तिगत वस्तुओं के लिए JSON स्कीमा सत्यापन का समर्थन।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**विभेदक संघ (Discriminated Unions)**: `type` फ़ील्ड का उपयोग करके मिश्रित-प्रकार के आउटपुट का समर्थन।
|
||||
विभेदक।
|
||||
**न्यूनतम एपीआई परिवर्तन (Minimal API Changes)**: नए प्रतिक्रिया प्रकार और स्कीमा कुंजी के साथ मौजूदा प्रॉम्प्ट कॉन्फ़िगरेशन का विस्तार।
|
||||
|
||||
|
||||
## पृष्ठभूमि
|
||||
|
||||
### वर्तमान आर्किटेक्चर
|
||||
|
||||
प्रॉम्प्ट सेवा दो प्रकार के प्रतिक्रियाओं का समर्थन करती है:
|
||||
|
||||
1. `response-type: "text"` - बिना किसी बदलाव के वापस की गई कच्ची टेक्स्ट प्रतिक्रिया
|
||||
<<<<<<< HEAD
|
||||
2. `response-type: "json"` - प्रतिक्रिया से पार्स किया गया JSON, जिसकी जाँच `response-type: "json"` के विरुद्ध की जाती है
|
||||
वैकल्पिक `schema`
|
||||
|
||||
`trustgraph-flow/trustgraph/template/prompt_manager.py` में वर्तमान कार्यान्वयन:
|
||||
=======
|
||||
2. `response-type: "json"` - प्रतिक्रिया से पार्स किया गया JSON, जिसकी तुलना
|
||||
वैकल्पिक `schema` से की जाती है
|
||||
|
||||
वर्तमान कार्यान्वयन `trustgraph-flow/trustgraph/template/prompt_manager.py` में:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
```python
|
||||
class Prompt:
|
||||
def __init__(self, template, response_type = "text", terms=None, schema=None):
|
||||
self.template = template
|
||||
self.response_type = response_type
|
||||
self.terms = terms
|
||||
self.schema = schema
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
### वर्तमान सीमाएँ
|
||||
|
||||
जब निष्कर्षण प्रॉम्प्ट आउटपुट को JSON सरणियों (`[{...}, {...}, ...]`) के रूप में मांगते हैं:
|
||||
|
||||
**अतिसंक्षेपण भ्रष्टाचार**: यदि LLM आउटपुट टोकन सीमाओं को सरणी के बीच में पार करता है, तो
|
||||
संपूर्ण प्रतिक्रिया अमान्य JSON बन जाती है और इसे पार्स नहीं किया जा सकता है।
|
||||
**सब कुछ या कुछ नहीं पार्सिंग**: पार्स करने से पहले पूर्ण आउटपुट प्राप्त करना आवश्यक है।
|
||||
**कोई आंशिक परिणाम नहीं**: एक छोटा आउटपुट शून्य उपयोगी डेटा उत्पन्न करता है।
|
||||
**बड़े निष्कर्षणों के लिए अविश्वसनीय**: अधिक निकाले गए आइटम = उच्च विफलता जोखिम।
|
||||
|
||||
यह विनिर्देश इन सीमाओं को JSONL प्रारूप को पेश करके संबोधित करता है, जहाँ प्रत्येक निकाले गए आइटम को अपनी
|
||||
=======
|
||||
### वर्तमान सीमाएं
|
||||
|
||||
जब निष्कर्षण प्रॉम्प्ट आउटपुट को JSON सरणियों (`[{...}, {...}, ...]`) के रूप में मांगते हैं:
|
||||
|
||||
**अतिसंयोजन भ्रष्टाचार**: यदि LLM आउटपुट टोकन सीमाओं को सरणी के बीच में पार करता है, तो
|
||||
संपूर्ण प्रतिक्रिया अमान्य JSON बन जाती है और इसे पार्स नहीं किया जा सकता है।
|
||||
**सब कुछ या कुछ नहीं पार्सिंग**: पार्स करने से पहले पूर्ण आउटपुट प्राप्त करना आवश्यक है।
|
||||
**कोई आंशिक परिणाम नहीं**: एकtruncated प्रतिक्रिया शून्य उपयोगी डेटा उत्पन्न करती है।
|
||||
**बड़े निष्कर्षणों के लिए अविश्वसनीय**: अधिक निकाले गए आइटम = उच्च विफलता जोखिम।
|
||||
|
||||
यह विनिर्देश इन सीमाओं को JSONL प्रारूप को पेश करके संबोधित करता है, जहां प्रत्येक निकाले गए आइटम को अपनी
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
पंक्ति पर एक पूर्ण JSON ऑब्जेक्ट के रूप में दर्शाया जाता है।
|
||||
|
||||
|
||||
## तकनीकी डिज़ाइन
|
||||
|
||||
### प्रतिक्रिया प्रकार विस्तार
|
||||
|
||||
मौजूदा `"text"` और `"json"` प्रकारों के साथ एक नया प्रतिक्रिया प्रकार `"jsonl"` जोड़ें।
|
||||
|
||||
#### कॉन्फ़िगरेशन परिवर्तन
|
||||
|
||||
**नया प्रतिक्रिया प्रकार मान:**
|
||||
|
||||
```
|
||||
"response-type": "jsonl"
|
||||
```
|
||||
|
||||
**स्कीमा व्याख्या:**
|
||||
|
||||
मौजूदा `"schema"` कुंजी का उपयोग `"json"` और `"jsonl"` दोनों प्रतिक्रिया प्रकारों के लिए किया जाता है।
|
||||
व्याख्या प्रतिक्रिया के प्रकार पर निर्भर करती है:
|
||||
|
||||
`"json"`: स्कीमा संपूर्ण प्रतिक्रिया का वर्णन करता है (आमतौर पर एक सरणी या ऑब्जेक्ट)।
|
||||
`"jsonl"`: स्कीमा प्रत्येक व्यक्तिगत पंक्ति/ऑब्जेक्ट का वर्णन करता है।
|
||||
|
||||
```json
|
||||
{
|
||||
"response-type": "jsonl",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"entity": { "type": "string" },
|
||||
"definition": { "type": "string" }
|
||||
},
|
||||
"required": ["entity", "definition"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
यह प्रॉम्प्ट कॉन्फ़िगरेशन टूलिंग और संपादकों में बदलावों से बचाता है।
|
||||
|
||||
### JSONL प्रारूप विनिर्देश
|
||||
|
||||
#### सरल निष्कर्षण
|
||||
|
||||
उन प्रॉम्प्ट के लिए जो केवल एक प्रकार की वस्तु (परिभाषाएँ, संबंध,
|
||||
<<<<<<< HEAD
|
||||
विषय, पंक्तियाँ) निकालते हैं, आउटपुट में बिना किसी अतिरिक्त आवरण के प्रति पंक्ति एक JSON ऑब्जेक्ट होता है:
|
||||
=======
|
||||
विषय, पंक्तियाँ) निकालते हैं, आउटपुट में बिना किसी अतिरिक्त आवरण के, प्रति पंक्ति एक JSON ऑब्जेक्ट होता है:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**प्रॉम्प्ट आउटपुट प्रारूप:**
|
||||
```
|
||||
{"entity": "photosynthesis", "definition": "Process by which plants convert sunlight"}
|
||||
{"entity": "chlorophyll", "definition": "Green pigment in plants"}
|
||||
{"entity": "mitochondria", "definition": "Powerhouse of the cell"}
|
||||
```
|
||||
|
||||
**पिछले JSON सरणी प्रारूप के साथ अंतर:**
|
||||
```json
|
||||
[
|
||||
{"entity": "photosynthesis", "definition": "Process by which plants convert sunlight"},
|
||||
{"entity": "chlorophyll", "definition": "Green pigment in plants"},
|
||||
{"entity": "mitochondria", "definition": "Powerhouse of the cell"}
|
||||
]
|
||||
```
|
||||
|
||||
यदि एलएलएम (LLM) दूसरी पंक्ति के बाद कट जाता है, तो JSON सरणी प्रारूप अमान्य JSON उत्पन्न करता है,
|
||||
जबकि JSONL दो मान्य ऑब्जेक्ट उत्पन्न करता है।
|
||||
|
||||
#### मिश्रित-प्रकार निष्कर्षण (भेदभावपूर्ण संघ)
|
||||
|
||||
<<<<<<< HEAD
|
||||
उन प्रॉम्प्ट के लिए जो ऑब्जेक्ट के कई प्रकारों को निकालते हैं (उदाहरण के लिए, परिभाषाएँ और
|
||||
संबंध, या इकाइयाँ, संबंध और विशेषताएँ), एक `"type"`
|
||||
फ़ील्ड को विभेदक के रूप में उपयोग करें:
|
||||
=======
|
||||
उन प्रॉम्प्ट के लिए जो कई प्रकार की वस्तुओं को निकालते हैं (उदाहरण के लिए, परिभाषाएँ और
|
||||
संबंध, या इकाइयाँ, संबंध और विशेषताएँ), एक `"type"`
|
||||
फ़ील्ड का उपयोग विभेदक के रूप में करें:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**प्रॉम्प्ट आउटपुट प्रारूप:**
|
||||
```
|
||||
{"type": "definition", "entity": "DNA", "definition": "Molecule carrying genetic instructions"}
|
||||
{"type": "relationship", "subject": "DNA", "predicate": "located_in", "object": "cell nucleus", "object-entity": true}
|
||||
{"type": "definition", "entity": "RNA", "definition": "Molecule that carries genetic information"}
|
||||
{"type": "relationship", "subject": "RNA", "predicate": "transcribed_from", "object": "DNA", "object-entity": true}
|
||||
```
|
||||
|
||||
**विभेदक संघों के लिए स्कीमा `oneOf` का उपयोग करता है:**
|
||||
```json
|
||||
{
|
||||
"response-type": "jsonl",
|
||||
"schema": {
|
||||
"oneOf": [
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"type": { "const": "definition" },
|
||||
"entity": { "type": "string" },
|
||||
"definition": { "type": "string" }
|
||||
},
|
||||
"required": ["type", "entity", "definition"]
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"type": { "const": "relationship" },
|
||||
"subject": { "type": "string" },
|
||||
"predicate": { "type": "string" },
|
||||
"object": { "type": "string" },
|
||||
"object-entity": { "type": "boolean" }
|
||||
},
|
||||
"required": ["type", "subject", "predicate", "object", "object-entity"]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### शब्दावली निष्कर्षण
|
||||
|
||||
संस्थाओं, संबंधों और विशेषताओं के साथ शब्दावली-आधारित निष्कर्षण के लिए:
|
||||
|
||||
**प्रॉम्प्ट आउटपुट प्रारूप:**
|
||||
```
|
||||
{"type": "entity", "entity": "Cornish pasty", "entity_type": "fo/Recipe"}
|
||||
{"type": "entity", "entity": "beef", "entity_type": "fo/Food"}
|
||||
{"type": "relationship", "subject": "Cornish pasty", "subject_type": "fo/Recipe", "relation": "fo/has_ingredient", "object": "beef", "object_type": "fo/Food"}
|
||||
{"type": "attribute", "entity": "Cornish pasty", "entity_type": "fo/Recipe", "attribute": "fo/serves", "value": "4 people"}
|
||||
```
|
||||
|
||||
### कार्यान्वयन विवरण
|
||||
|
||||
#### प्रॉम्प्ट क्लास
|
||||
|
||||
मौजूदा `Prompt` क्लास में कोई बदलाव आवश्यक नहीं है। `schema` फ़ील्ड का पुन: उपयोग किया गया है।
|
||||
JSONL के लिए, जिसका अर्थ `response_type` द्वारा निर्धारित किया जाता है:
|
||||
|
||||
```python
|
||||
class Prompt:
|
||||
def __init__(self, template, response_type="text", terms=None, schema=None):
|
||||
self.template = template
|
||||
self.response_type = response_type
|
||||
self.terms = terms
|
||||
self.schema = schema # Interpretation depends on response_type
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
#### प्रॉम्प्टमैनेजर.लोड_कॉन्फ़िगरेशन
|
||||
=======
|
||||
#### PromptManager.load_config
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
कोई बदलाव आवश्यक नहीं है - मौजूदा कॉन्फ़िगरेशन लोड करने की प्रक्रिया पहले से ही
|
||||
`schema` कुंजी को संभालती है।
|
||||
|
||||
#### JSONL पार्सिंग
|
||||
|
||||
JSONL प्रतिक्रियाओं के लिए एक नई पार्सिंग विधि जोड़ें:
|
||||
|
||||
```python
|
||||
def parse_jsonl(self, text):
|
||||
"""
|
||||
Parse JSONL response, returning list of valid objects.
|
||||
|
||||
Invalid lines (malformed JSON, empty lines) are skipped with warnings.
|
||||
This provides truncation resilience - partial output yields partial results.
|
||||
"""
|
||||
results = []
|
||||
|
||||
for line_num, line in enumerate(text.strip().split('\n'), 1):
|
||||
line = line.strip()
|
||||
|
||||
# Skip empty lines
|
||||
if not line:
|
||||
continue
|
||||
|
||||
# Skip markdown code fence markers if present
|
||||
if line.startswith('```'):
|
||||
continue
|
||||
|
||||
try:
|
||||
obj = json.loads(line)
|
||||
results.append(obj)
|
||||
except json.JSONDecodeError as e:
|
||||
# Log warning but continue - this provides truncation resilience
|
||||
logger.warning(f"JSONL parse error on line {line_num}: {e}")
|
||||
|
||||
return results
|
||||
```
|
||||
|
||||
#### प्रॉम्प्टमैनेजर.इनवॉइक में बदलाव
|
||||
|
||||
इनवॉइक विधि को नए प्रतिक्रिया प्रकार को संभालने के लिए विस्तारित करें:
|
||||
|
||||
```python
|
||||
async def invoke(self, id, input, llm):
|
||||
logger.debug("Invoking prompt template...")
|
||||
|
||||
terms = self.terms | self.prompts[id].terms | input
|
||||
resp_type = self.prompts[id].response_type
|
||||
|
||||
prompt = {
|
||||
"system": self.system_template.render(terms),
|
||||
"prompt": self.render(id, input)
|
||||
}
|
||||
|
||||
resp = await llm(**prompt)
|
||||
|
||||
if resp_type == "text":
|
||||
return resp
|
||||
|
||||
if resp_type == "json":
|
||||
try:
|
||||
obj = self.parse_json(resp)
|
||||
except:
|
||||
logger.error(f"JSON parse failed: {resp}")
|
||||
raise RuntimeError("JSON parse fail")
|
||||
|
||||
if self.prompts[id].schema:
|
||||
try:
|
||||
validate(instance=obj, schema=self.prompts[id].schema)
|
||||
logger.debug("Schema validation successful")
|
||||
except Exception as e:
|
||||
raise RuntimeError(f"Schema validation fail: {e}")
|
||||
|
||||
return obj
|
||||
|
||||
if resp_type == "jsonl":
|
||||
objects = self.parse_jsonl(resp)
|
||||
|
||||
if not objects:
|
||||
logger.warning("JSONL parse returned no valid objects")
|
||||
return []
|
||||
|
||||
# Validate each object against schema if provided
|
||||
if self.prompts[id].schema:
|
||||
validated = []
|
||||
for i, obj in enumerate(objects):
|
||||
try:
|
||||
validate(instance=obj, schema=self.prompts[id].schema)
|
||||
validated.append(obj)
|
||||
except Exception as e:
|
||||
logger.warning(f"Object {i} failed schema validation: {e}")
|
||||
return validated
|
||||
|
||||
return objects
|
||||
|
||||
raise RuntimeError(f"Response type {resp_type} not known")
|
||||
```
|
||||
|
||||
### प्रभावित संकेत (प्रॉम्प्ट)
|
||||
|
||||
निम्नलिखित संकेतों को JSONL प्रारूप में स्थानांतरित किया जाना चाहिए:
|
||||
|
||||
| संकेत आईडी | विवरण | प्रकार फ़ील्ड |
|
||||
|-----------|-------------|------------|
|
||||
| `extract-definitions` | इकाई/परिभाषा निष्कर्षण | नहीं (एकल प्रकार) |
|
||||
| `extract-relationships` | संबंध निष्कर्षण | नहीं (एकल प्रकार) |
|
||||
| `extract-topics` | विषय/परिभाषा निष्कर्षण | नहीं (एकल प्रकार) |
|
||||
| `extract-rows` | संरचित पंक्ति निष्कर्षण | नहीं (एकल प्रकार) |
|
||||
| `agent-kg-extract` | संयुक्त परिभाषा + संबंध निष्कर्षण | हाँ: `"definition"`, `"relationship"` |
|
||||
| `extract-with-ontologies` / `ontology-extract` | ज्ञान-आधारित निष्कर्षण | हाँ: `"entity"`, `"relationship"`, `"attribute"` |
|
||||
|
||||
### एपीआई में बदलाव
|
||||
|
||||
#### क्लाइंट का दृष्टिकोण
|
||||
|
||||
JSONL पार्सिंग, प्रॉम्प्ट सर्विस एपीआई उपयोगकर्ताओं के लिए पारदर्शी है। पार्सिंग प्रॉम्प्ट सर्विस में सर्वर-साइड पर होता है, और प्रतिक्रिया मानक ⟦CODE_0⟧ फ़ील्ड के रूप में एक क्रमबद्ध JSON सरणी के माध्यम से वापस की जाती है।
|
||||
|
||||
`PromptResponse.object`
|
||||
|
||||
जब ग्राहक प्रॉम्प्ट सेवा को कॉल करते हैं (`PromptClient.prompt()` या इसी तरह के माध्यम से):
|
||||
|
||||
**`response-type: "json"`** जिसमें एरे स्कीमा है → ग्राहक को पायथन `list` प्राप्त होता है।
|
||||
**`response-type: "jsonl"`** → ग्राहक को पायथन `list` प्राप्त होता है।
|
||||
|
||||
<<<<<<< HEAD
|
||||
ग्राहक के दृष्टिकोण से, दोनों समान डेटा संरचनाएं लौटाते हैं।
|
||||
अंतर पूरी तरह से इस बात में है कि सर्वर-साइड पर एलएलएम आउटपुट को कैसे पार्स किया जाता है:
|
||||
|
||||
JSON सरणी प्रारूप: एक `json.loads()` कॉल; यदि छोटा किया गया तो पूरी तरह से विफल हो जाता है।
|
||||
JSONL प्रारूप: लाइन-दर-लाइन पार्सिंग; यदि छोटा किया गया तो आंशिक परिणाम देता है।
|
||||
=======
|
||||
ग्राहक के दृष्टिकोण से, दोनों समान डेटा संरचनाएँ लौटाते हैं।
|
||||
अंतर पूरी तरह से इस बात में है कि सर्वर-साइड पर एलएलएम आउटपुट को कैसे पार्स किया जाता है:
|
||||
|
||||
JSON सरणी प्रारूप: एक `json.loads()` कॉल; यदि छोटा किया गया तो पूरी तरह विफल हो जाता है।
|
||||
JSONL प्रारूप: पंक्ति-दर-पंक्ति पार्सिंग; यदि छोटा किया गया तो आंशिक परिणाम देता है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
इसका मतलब है कि मौजूदा क्लाइंट कोड जो एक्सट्रैक्शन प्रॉम्प्ट से एक सूची की अपेक्षा करता है,
|
||||
को JSON से JSONL प्रारूप में प्रॉम्प्ट माइग्रेट करते समय किसी भी बदलाव की आवश्यकता नहीं होती है।
|
||||
|
||||
#### सर्वर रिटर्न वैल्यू
|
||||
|
||||
`response-type: "jsonl"` के लिए, `PromptManager.invoke()` विधि एक
|
||||
<<<<<<< HEAD
|
||||
`list[dict]` लौटाती है जिसमें सभी सफलतापूर्वक पार्स और मान्य किए गए ऑब्जेक्ट शामिल होते हैं। इस
|
||||
=======
|
||||
`list[dict]` लौटाती है जिसमें सभी सफलतापूर्वक पार्स किए गए और मान्य ऑब्जेक्ट शामिल हैं। इस
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
सूची को तब `PromptResponse.object` फ़ील्ड के लिए JSON में क्रमबद्ध किया जाता है।
|
||||
|
||||
#### त्रुटि प्रबंधन
|
||||
|
||||
<<<<<<< HEAD
|
||||
खाली परिणाम: खाली सूची `[]` लौटाता है चेतावनी लॉग के साथ।
|
||||
आंशिक पार्स विफलता: सफलतापूर्वक पार्स किए गए ऑब्जेक्ट की सूची लौटाता है,
|
||||
विफलताओं के लिए चेतावनी लॉग के साथ।
|
||||
पूर्ण पार्स विफलता: खाली सूची `[]` लौटाता है, चेतावनी लॉग के साथ।
|
||||
|
||||
यह `response-type: "json"` से अलग है, जो पार्स विफलता पर `RuntimeError` उत्पन्न करता है।
|
||||
=======
|
||||
खाली परिणाम: खाली सूची `[]` लौटाता है, साथ में चेतावनी लॉग।
|
||||
आंशिक पार्स विफलता: सफलतापूर्वक पार्स किए गए ऑब्जेक्ट की सूची लौटाता है,
|
||||
विफलताओं के लिए चेतावनी लॉग के साथ।
|
||||
पूर्ण पार्स विफलता: खाली सूची `[]` लौटाता है, साथ में चेतावनी लॉग।
|
||||
|
||||
यह `response-type: "json"` से भिन्न है, जो पार्स विफलता पर `RuntimeError` उत्पन्न करता है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
JSONL के लिए उदार व्यवहार जानबूझकर प्रदान किया गया है ताकि ट्रंकेशन के प्रति लचीलापन मिल सके।
|
||||
|
||||
|
||||
### कॉन्फ़िगरेशन उदाहरण
|
||||
|
||||
पूर्ण प्रॉम्प्ट कॉन्फ़िगरेशन उदाहरण:
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": "Extract all entities and their definitions from the following text. Output one JSON object per line.\n\nText:\n{{text}}\n\nOutput format per line:\n{\"entity\": \"<name>\", \"definition\": \"<definition>\"}",
|
||||
"response-type": "jsonl",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"entity": {
|
||||
"type": "string",
|
||||
"description": "The entity name"
|
||||
},
|
||||
"definition": {
|
||||
"type": "string",
|
||||
"description": "A clear definition of the entity"
|
||||
}
|
||||
},
|
||||
"required": ["entity", "definition"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## सुरक्षा संबंधी विचार
|
||||
|
||||
**इनपुट सत्यापन**: JSON पार्सिंग मानक `json.loads()` का उपयोग करता है, जो इंजेक्शन हमलों के खिलाफ सुरक्षित है।
|
||||
**स्कीमा सत्यापन**: स्कीमा प्रवर्तन के लिए ⟦CODE_0⟧ का उपयोग करता है।
|
||||
**स्कीमा सत्यापन**: स्कीमा के अनुपालन को सुनिश्चित करने के लिए `jsonschema.validate()` का उपयोग करता है।
|
||||
**कोई नया आक्रमण क्षेत्र नहीं**: JSONL पार्सिंग, लाइन-दर-लाइन प्रसंस्करण के कारण, JSON सरणी पार्सिंग की तुलना में बहुत अधिक सुरक्षित है।
|
||||
|
||||
|
||||
## प्रदर्शन संबंधी विचार
|
||||
|
||||
<<<<<<< HEAD
|
||||
**मेमोरी**: पंक्ति-दर-पंक्ति पार्सिंग, पूरे JSON सरणियों को लोड करने की तुलना में कम चरम मेमोरी का उपयोग करती है।
|
||||
=======
|
||||
**मेमोरी**: लाइन-दर-लाइन पार्सिंग, पूरे JSON सरणियों को लोड करने की तुलना में कम चरम मेमोरी का उपयोग करती है।
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**विलंबता**: पार्सिंग प्रदर्शन, JSON सरणी पार्सिंग के समान है।
|
||||
**सत्यापन**: स्कीमा सत्यापन प्रत्येक ऑब्जेक्ट के लिए किया जाता है, जिससे ओवरहेड बढ़ता है, लेकिन सत्यापन विफलता पर आंशिक परिणाम प्राप्त करने की अनुमति मिलती है।
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
### यूनिट परीक्षण (Unit Tests)
|
||||
|
||||
मान्य इनपुट के साथ JSONL पार्सिंग
|
||||
खाली पंक्तियों के साथ JSONL पार्सिंग
|
||||
मार्कडाउन कोड फ़ेंस के साथ JSONL पार्सिंग
|
||||
<<<<<<< HEAD
|
||||
कटे हुए अंतिम पंक्ति के साथ JSONL पार्सिंग
|
||||
=======
|
||||
truncated अंतिम पंक्ति के साथ JSONL पार्सिंग
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
अमान्य JSON पंक्तियों के साथ JSONL पार्सिंग
|
||||
`oneOf` विभेदक संघों के साथ स्कीमा सत्यापन
|
||||
पिछली अनुकूलता: मौजूदा `"text"` और `"json"` प्रॉम्प्ट अपरिवर्तित
|
||||
|
||||
### एकीकरण परीक्षण (Integration Tests)
|
||||
|
||||
JSONL प्रॉम्प्ट के साथ एंड-टू-एंड निष्कर्षण
|
||||
<<<<<<< HEAD
|
||||
अनुकरणित कटाई के साथ निष्कर्षण (कृत्रिम रूप से सीमित प्रतिक्रिया)
|
||||
=======
|
||||
अनुकरणित ट्रंकेशन के साथ निष्कर्षण (कृत्रिम रूप से सीमित प्रतिक्रिया)
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
टाइप डिस्क्रिमिनेटर के साथ मिश्रित-प्रकार निष्कर्षण
|
||||
सभी तीन प्रकारों के साथ ऑन्टोलॉजी निष्कर्षण
|
||||
|
||||
### निष्कर्षण गुणवत्ता परीक्षण (Extraction Quality Tests)
|
||||
|
||||
निष्कर्षण परिणामों की तुलना करें: JSONL बनाम JSON सरणी प्रारूप
|
||||
ट्रंकेशन के प्रति लचीलापन की जाँच करें: JSONL आंशिक परिणाम देता है जहाँ JSON विफल रहता है
|
||||
|
||||
## माइग्रेशन योजना
|
||||
|
||||
### चरण 1: कार्यान्वयन
|
||||
|
||||
1. `parse_jsonl()` विधि को `PromptManager` में लागू करें
|
||||
2. `invoke()` को `response-type: "jsonl"` को संभालने के लिए विस्तारित करें
|
||||
3. यूनिट परीक्षण जोड़ें
|
||||
|
||||
### चरण 2: प्रॉम्प्ट माइग्रेशन
|
||||
|
||||
1. `extract-definitions` प्रॉम्प्ट और कॉन्फ़िगरेशन को अपडेट करें
|
||||
2. `extract-relationships` प्रॉम्प्ट और कॉन्फ़िगरेशन को अपडेट करें
|
||||
3. `extract-topics` प्रॉम्प्ट और कॉन्फ़िगरेशन को अपडेट करें
|
||||
4. `extract-rows` प्रॉम्प्ट और कॉन्फ़िगरेशन को अपडेट करें
|
||||
5. `agent-kg-extract` प्रॉम्प्ट और कॉन्फ़िगरेशन को अपडेट करें
|
||||
6. `extract-with-ontologies` प्रॉम्प्ट और कॉन्फ़िगरेशन को अपडेट करें
|
||||
|
||||
### चरण 3: डाउनस्ट्रीम अपडेट
|
||||
|
||||
1. निष्कर्षण परिणामों का उपयोग करने वाले किसी भी कोड को सूची रिटर्न प्रकार को संभालने के लिए अपडेट करें
|
||||
2. `type` फ़ील्ड द्वारा मिश्रित-प्रकार के निष्कर्षणों को वर्गीकृत करने वाले कोड को अपडेट करें
|
||||
<<<<<<< HEAD
|
||||
3. निष्कर्षण आउटपुट प्रारूप पर दावा करने वाले परीक्षणों को अपडेट करें
|
||||
=======
|
||||
3. निष्कर्षण आउटपुट प्रारूप पर जोर देने वाले परीक्षणों को अपडेट करें
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## खुले प्रश्न
|
||||
|
||||
फिलहाल कोई नहीं।
|
||||
|
||||
## संदर्भ
|
||||
|
||||
वर्तमान कार्यान्वयन: `trustgraph-flow/trustgraph/template/prompt_manager.py`
|
||||
JSON लाइन्स विनिर्देश: https://jsonlines.org/
|
||||
JSON स्कीमा `oneOf`: https://json-schema.org/understanding-json-schema/reference/combining.html#oneof
|
||||
संबंधित विनिर्देश: स्ट्रीमिंग LLM प्रतिक्रियाएँ (`docs/tech-specs/streaming-llm-responses.md`)
|
||||
992
docs/tech-specs/hi/large-document-loading.hi.md
Normal file
992
docs/tech-specs/hi/large-document-loading.hi.md
Normal file
|
|
@ -0,0 +1,992 @@
|
|||
---
|
||||
layout: default
|
||||
title: "बड़े दस्तावेज़ लोडिंग के लिए तकनीकी विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# बड़े दस्तावेज़ लोडिंग के लिए तकनीकी विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह विनिर्देश स्केलेबिलिटी और उपयोगकर्ता अनुभव से संबंधित मुद्दों को संबोधित करता है जो तब उत्पन्न होते हैं जब TrustGraph में बड़े दस्तावेज़ लोड किए जाते हैं। वर्तमान आर्किटेक्चर दस्तावेज़ अपलोड को एक एकल, अविभाज्य ऑपरेशन के रूप में मानता है, जिससे पाइपलाइन के कई बिंदुओं पर मेमोरी का दबाव पड़ता है और उपयोगकर्ताओं को कोई प्रतिक्रिया या रिकवरी विकल्प नहीं मिलते हैं।
|
||||
|
||||
यह कार्यान्वयन निम्नलिखित उपयोग मामलों को लक्षित करता है:
|
||||
|
||||
|
||||
|
||||
|
||||
1. **बड़े पीडीएफ प्रसंस्करण**: सैकड़ों मेगाबाइट के पीडीएफ फ़ाइलों को अपलोड करें और संसाधित करें
|
||||
बिना मेमोरी समाप्त किए।
|
||||
2. **फिर से शुरू करने योग्य अपलोड**: बाधित अपलोड को वहीं से जारी करने की अनुमति दें जहां से
|
||||
वे रुके थे, न कि पुनः आरंभ करने के बजाय।
|
||||
3. **प्रगति प्रतिक्रिया**: उपयोगकर्ताओं को अपलोड और प्रसंस्करण की वास्तविक समय की जानकारी प्रदान करें।
|
||||
4. **मेमोरी-कुशल प्रसंस्करण**: दस्तावेज़ों को स्ट्रीमिंग तरीके से संसाधित करें
|
||||
बिना पूरी फ़ाइलों को मेमोरी में रखे।
|
||||
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
**क्रमिक अपलोड**: REST और WebSocket के माध्यम से खंडित दस्तावेज़ अपलोड का समर्थन।
|
||||
**फिर से शुरू करने योग्य स्थानांतरण**: बाधित अपलोड से उबरने की क्षमता।
|
||||
**प्रगति दृश्यता**: क्लाइंट को अपलोड/प्रोसेसिंग प्रगति प्रतिक्रिया प्रदान करें।
|
||||
**मेमोरी दक्षता**: पाइपलाइन में पूरे दस्तावेज़ को बफर करने से बचें।
|
||||
**पिछड़ा संगतता**: मौजूदा छोटे दस्तावेज़ वर्कफ़्लो बिना किसी बदलाव के जारी रहते हैं।
|
||||
**स्ट्रीमिंग प्रोसेसिंग**: PDF डिकोडिंग और टेक्स्ट चंकिंग स्ट्रीम पर काम करते हैं।
|
||||
|
||||
## पृष्ठभूमि
|
||||
|
||||
### वर्तमान आर्किटेक्चर
|
||||
|
||||
दस्तावेज़ सबमिशन निम्नलिखित पथ से गुजरता है:
|
||||
|
||||
1. **क्लाइंट** REST (`POST /api/v1/librarian`) या WebSocket के माध्यम से दस्तावेज़ सबमिट करता है।
|
||||
2. **API गेटवे** बेस64-एन्कोडेड दस्तावेज़ सामग्री के साथ पूर्ण अनुरोध प्राप्त करता है।
|
||||
3. **LibrarianRequestor** अनुरोध को Pulsar संदेश में बदलता है।
|
||||
4. **Librarian सर्विस** संदेश प्राप्त करता है, दस्तावेज़ को मेमोरी में डिकोड करता है।
|
||||
5. **BlobStore** दस्तावेज़ को Garage/S3 पर अपलोड करता है।
|
||||
6. **Cassandra** ऑब्जेक्ट संदर्भ के साथ मेटाडेटा संग्रहीत करता है।
|
||||
7. प्रोसेसिंग के लिए: दस्तावेज़ को S3 से पुनर्प्राप्त किया जाता है, डिकोड किया जाता है, खंडित किया जाता है - सभी मेमोरी में।
|
||||
|
||||
मुख्य फाइलें:
|
||||
REST/WebSocket एंट्री: `trustgraph-flow/trustgraph/gateway/service.py`
|
||||
Librarian कोर: `trustgraph-flow/trustgraph/librarian/librarian.py`
|
||||
Blob स्टोरेज: `trustgraph-flow/trustgraph/librarian/blob_store.py`
|
||||
Cassandra टेबल: `trustgraph-flow/trustgraph/tables/library.py`
|
||||
API स्कीमा: `trustgraph-base/trustgraph/schema/services/library.py`
|
||||
|
||||
### वर्तमान सीमाएँ
|
||||
|
||||
वर्तमान डिज़ाइन में कई जटिल मेमोरी और उपयोगकर्ता अनुभव संबंधी समस्याएं हैं:
|
||||
|
||||
1. **परमाणु अपलोड ऑपरेशन**: संपूर्ण दस्तावेज़ को एक
|
||||
एकल अनुरोध में प्रेषित किया जाना चाहिए। बड़े दस्तावेज़ों के लिए लंबे समय तक चलने वाले अनुरोधों की आवश्यकता होती है, जिसमें कोई प्रगति संकेत नहीं होता है और यदि कनेक्शन विफल हो जाता है तो कोई पुनः प्रयास तंत्र नहीं होता है।
|
||||
|
||||
|
||||
2. **एपीआई डिज़ाइन**: REST और WebSocket दोनों एपीआई संपूर्ण दस्तावेज़ की अपेक्षा करते हैं
|
||||
एक ही संदेश में। स्कीमा (`LibrarianRequest`) में एक `content`
|
||||
फ़ील्ड है जिसमें संपूर्ण बेस64-एन्कोडेड दस्तावेज़ होता है।
|
||||
|
||||
3. **लाइब्रेरियन मेमोरी**: लाइब्रेरियन सेवा पूरे दस्तावेज़ को
|
||||
मेमोरी में डिकोड करती है, फिर इसे S3 पर अपलोड करने से पहले। 500MB के PDF के लिए, इसका मतलब है कि 500MB+ को प्रोसेस मेमोरी में रखना।
|
||||
500MB+ को प्रोसेस मेमोरी में रखना।
|
||||
|
||||
4. **PDF डिकोडर मेमोरी**: जब प्रोसेसिंग शुरू होती है, तो PDF डिकोडर टेक्स्ट निकालने के लिए पूरे PDF को मेमोरी में लोड करता है। PyPDF और समान लाइब्रेरीज़ को आमतौर पर पूरे दस्तावेज़ तक पहुंच की आवश्यकता होती है।
|
||||
PyPDF और समान लाइब्रेरीज़ को आमतौर पर पूरे दस्तावेज़ तक पहुंच की आवश्यकता होती है।
|
||||
|
||||
|
||||
5. **चंकर मेमोरी**: टेक्स्ट चंकर, निकाले गए पूरे टेक्स्ट को प्राप्त करता है
|
||||
और इसे मेमोरी में रखता है, जबकि चंक्स बनाता है।
|
||||
|
||||
**मेमोरी प्रभाव का उदाहरण** (500MB पीडीएफ):
|
||||
गेटवे: ~700MB (बेस64 एन्कोडिंग ओवरहेड)
|
||||
लाइब्रेरियन: ~500MB (डिकोडेड बाइट्स)
|
||||
पीडीएफ डिकोडर: ~500MB + एक्सट्रैक्शन बफ़र्स
|
||||
चंकर: निकाला गया टेक्स्ट (चर, संभावित रूप से 100MB+)
|
||||
|
||||
एक बड़े दस्तावेज़ के लिए कुल अधिकतम मेमोरी 2GB से अधिक हो सकती है।
|
||||
|
||||
## तकनीकी डिज़ाइन
|
||||
|
||||
### डिज़ाइन सिद्धांत
|
||||
|
||||
1. **एपीआई फ़ेसड**: सभी क्लाइंट इंटरैक्शन लाइब्रेरियन एपीआई के माध्यम से होते हैं। क्लाइंट
|
||||
के पास अंतर्निहित S3/गैराज स्टोरेज तक प्रत्यक्ष पहुंच या ज्ञान नहीं है।
|
||||
|
||||
2. **एस3 मल्टीपार्ट अपलोड**: आंतरिक रूप से मानक एस3 मल्टीपार्ट अपलोड का उपयोग करें।
|
||||
यह एस3-संगत प्रणालियों (AWS S3, MinIO, Garage,
|
||||
Ceph, DigitalOcean Spaces, Backblaze B2, आदि) में व्यापक रूप से समर्थित है, जो पोर्टेबिलिटी सुनिश्चित करता है।
|
||||
|
||||
3. **परमाणु पूर्णता**: एस3 मल्टीपार्ट अपलोड स्वाभाविक रूप से परमाणु होते हैं - अपलोड किए गए
|
||||
भाग तब तक अदृश्य रहते हैं जब तक कि `CompleteMultipartUpload` को कॉल नहीं किया जाता। कोई अस्थायी
|
||||
फ़ाइलें या नाम बदलने की क्रियाएं आवश्यक नहीं हैं।
|
||||
|
||||
4. **ट्रैक करने योग्य स्थिति**: अपलोड सत्रों को कैसेंड्रा में ट्रैक किया जाता है, जो
|
||||
अपूर्ण अपलोडों में दृश्यता प्रदान करता है और पुनः आरंभ करने की क्षमता को सक्षम करता है।
|
||||
|
||||
### चंक्ड अपलोड प्रवाह
|
||||
|
||||
```
|
||||
Client Librarian API S3/Garage
|
||||
│ │ │
|
||||
│── begin-upload ───────────►│ │
|
||||
│ (metadata, size) │── CreateMultipartUpload ────►│
|
||||
│ │◄── s3_upload_id ─────────────│
|
||||
│◄── upload_id ──────────────│ (store session in │
|
||||
│ │ Cassandra) │
|
||||
│ │ │
|
||||
│── upload-chunk ───────────►│ │
|
||||
│ (upload_id, index, data) │── UploadPart ───────────────►│
|
||||
│ │◄── etag ─────────────────────│
|
||||
│◄── ack + progress ─────────│ (store etag in session) │
|
||||
│ ⋮ │ ⋮ │
|
||||
│ (repeat for all chunks) │ │
|
||||
│ │ │
|
||||
│── complete-upload ────────►│ │
|
||||
│ (upload_id) │── CompleteMultipartUpload ──►│
|
||||
│ │ (parts coalesced by S3) │
|
||||
│ │── store doc metadata ───────►│ Cassandra
|
||||
│◄── document_id ────────────│ (delete session) │
|
||||
```
|
||||
|
||||
क्लाइंट कभी भी सीधे S3 के साथ इंटरैक्ट नहीं करता है। लाइब्रेरियन हमारे चंक्ड अपलोड API और S3 मल्टीपार्ट ऑपरेशंस के बीच आंतरिक रूप से अनुवाद करता है।
|
||||
|
||||
### लाइब्रेरियन API ऑपरेशन
|
||||
### लाइब्रेरियन एपीआई ऑपरेशन
|
||||
|
||||
#### `begin-upload`
|
||||
|
||||
एक खंडित अपलोड सत्र शुरू करें।
|
||||
|
||||
अनुरोध:
|
||||
```json
|
||||
{
|
||||
"operation": "begin-upload",
|
||||
"document-metadata": {
|
||||
"id": "doc-123",
|
||||
"kind": "application/pdf",
|
||||
"title": "Large Document",
|
||||
"user": "user-id",
|
||||
"tags": ["tag1", "tag2"]
|
||||
},
|
||||
"total-size": 524288000,
|
||||
"chunk-size": 5242880
|
||||
}
|
||||
```
|
||||
|
||||
प्रतिक्रिया:
|
||||
```json
|
||||
{
|
||||
"upload-id": "upload-abc-123",
|
||||
"chunk-size": 5242880,
|
||||
"total-chunks": 100
|
||||
}
|
||||
```
|
||||
|
||||
लाइब्रेरियन:
|
||||
1. एक अद्वितीय `upload_id` और `object_id` उत्पन्न करता है (ब्लॉब स्टोरेज के लिए UUID)।
|
||||
2. S3 `CreateMultipartUpload` को कॉल करता है, `s3_upload_id` प्राप्त करता है।
|
||||
3. कैसेंड्रा में सत्र रिकॉर्ड बनाता है।
|
||||
4. `upload_id` को क्लाइंट को वापस करता है।
|
||||
|
||||
#### `upload-chunk`
|
||||
|
||||
एक सिंगल चंक अपलोड करें।
|
||||
|
||||
अनुरोध:
|
||||
```json
|
||||
{
|
||||
"operation": "upload-chunk",
|
||||
"upload-id": "upload-abc-123",
|
||||
"chunk-index": 0,
|
||||
"content": "<base64-encoded-chunk>"
|
||||
}
|
||||
```
|
||||
|
||||
प्रतिक्रिया:
|
||||
```json
|
||||
{
|
||||
"upload-id": "upload-abc-123",
|
||||
"chunk-index": 0,
|
||||
"chunks-received": 1,
|
||||
"total-chunks": 100,
|
||||
"bytes-received": 5242880,
|
||||
"total-bytes": 524288000
|
||||
}
|
||||
```
|
||||
|
||||
लाइब्रेरियन:
|
||||
1. `upload_id` द्वारा सत्र खोजें।
|
||||
2. स्वामित्व की पुष्टि करें (उपयोगकर्ता को सत्र निर्माता से मेल खाना चाहिए)।
|
||||
3. चंक डेटा के साथ S3 `UploadPart` को कॉल करें, `etag` प्राप्त करें।
|
||||
4. चंक इंडेक्स और ईटैग के साथ सत्र रिकॉर्ड को अपडेट करें।
|
||||
5. क्लाइंट को प्रगति वापस करें।
|
||||
|
||||
विफल चंक्स को फिर से प्रयास किया जा सकता है - बस उसी `chunk-index` को फिर से भेजें।
|
||||
|
||||
#### `complete-upload`
|
||||
|
||||
अपलोड को अंतिम रूप दें और दस्तावेज़ बनाएं।
|
||||
|
||||
अनुरोध:
|
||||
```json
|
||||
{
|
||||
"operation": "complete-upload",
|
||||
"upload-id": "upload-abc-123"
|
||||
}
|
||||
```
|
||||
|
||||
प्रतिक्रिया:
|
||||
```json
|
||||
{
|
||||
"document-id": "doc-123",
|
||||
"object-id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
लाइब्रेरियन:
|
||||
1. सत्र की जांच करता है, यह सुनिश्चित करता है कि सभी भाग प्राप्त हो गए हैं।
|
||||
2. पार्ट एटाग्स के साथ S3 `CompleteMultipartUpload` को कॉल करता है (S3 आंतरिक रूप से भागों को संयोजित करता है - लाइब्रेरियन के लिए शून्य मेमोरी लागत)।
|
||||
3. मेटाडेटा और ऑब्जेक्ट संदर्भ के साथ कैसेंड्रा में दस्तावेज़ रिकॉर्ड बनाता है।
|
||||
4. अपलोड सत्र रिकॉर्ड को हटाता है।
|
||||
5. क्लाइंट को दस्तावेज़ आईडी वापस करता है।
|
||||
6.
|
||||
|
||||
#### `abort-upload`
|
||||
|
||||
एक चल रहे अपलोड को रद्द करें।
|
||||
|
||||
अनुरोध:
|
||||
```json
|
||||
{
|
||||
"operation": "abort-upload",
|
||||
"upload-id": "upload-abc-123"
|
||||
}
|
||||
```
|
||||
|
||||
लाइब्रेरियन:
|
||||
1. एस3 `AbortMultipartUpload` को भागों को साफ़ करने के लिए कॉल करता है।
|
||||
2. कैसेंड्रा से सत्र रिकॉर्ड को हटाता है।
|
||||
|
||||
#### `get-upload-status`
|
||||
|
||||
अपलोड की स्थिति की जांच करें (रिज़्यूम क्षमता के लिए)।
|
||||
|
||||
अनुरोध:
|
||||
```json
|
||||
{
|
||||
"operation": "get-upload-status",
|
||||
"upload-id": "upload-abc-123"
|
||||
}
|
||||
```
|
||||
|
||||
प्रतिक्रिया:
|
||||
```json
|
||||
{
|
||||
"upload-id": "upload-abc-123",
|
||||
"state": "in-progress",
|
||||
"chunks-received": [0, 1, 2, 5, 6],
|
||||
"missing-chunks": [3, 4, 7, 8],
|
||||
"total-chunks": 100,
|
||||
"bytes-received": 36700160,
|
||||
"total-bytes": 524288000
|
||||
}
|
||||
```
|
||||
|
||||
#### `list-uploads`
|
||||
|
||||
किसी उपयोगकर्ता के लिए अपूर्ण अपलोड की सूची प्राप्त करें।
|
||||
|
||||
अनुरोध:
|
||||
```json
|
||||
{
|
||||
"operation": "list-uploads"
|
||||
}
|
||||
```
|
||||
|
||||
प्रतिक्रिया:
|
||||
```json
|
||||
{
|
||||
"uploads": [
|
||||
{
|
||||
"upload-id": "upload-abc-123",
|
||||
"document-metadata": { "title": "Large Document", ... },
|
||||
"progress": { "chunks-received": 43, "total-chunks": 100 },
|
||||
"created-at": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### अपलोड सेशन स्टोरेज
|
||||
|
||||
कैसेंड्रा में चल रहे अपलोड को ट्रैक करें:
|
||||
|
||||
```sql
|
||||
CREATE TABLE upload_session (
|
||||
upload_id text PRIMARY KEY,
|
||||
user text,
|
||||
document_id text,
|
||||
document_metadata text, -- JSON: title, kind, tags, comments, etc.
|
||||
s3_upload_id text, -- internal, for S3 operations
|
||||
object_id uuid, -- target blob ID
|
||||
total_size bigint,
|
||||
chunk_size int,
|
||||
total_chunks int,
|
||||
chunks_received map<int, text>, -- chunk_index → etag
|
||||
created_at timestamp,
|
||||
updated_at timestamp
|
||||
) WITH default_time_to_live = 86400; -- 24 hour TTL
|
||||
|
||||
CREATE INDEX upload_session_user ON upload_session (user);
|
||||
```
|
||||
|
||||
**टीटीएल व्यवहार:**
|
||||
सत्र 24 घंटे के बाद समाप्त हो जाते हैं यदि वे पूरे नहीं होते हैं।
|
||||
जब कैसेंड्रा टीटीएल समाप्त होता है, तो सत्र रिकॉर्ड हटा दिया जाता है।
|
||||
अनाथ एस3 भाग को एस3 लाइफसाइकिल नीति द्वारा साफ़ किया जाता है (बकेट पर कॉन्फ़िगर करें)।
|
||||
|
||||
### विफलता प्रबंधन और परमाणुता
|
||||
|
||||
**चंक अपलोड विफलता:**
|
||||
क्लाइंट विफल चंक को फिर से प्रयास करता है (समान `upload_id` और `chunk-index`)।
|
||||
एस3 `UploadPart` समान भाग संख्या के लिए अपरिवर्तनीय है।
|
||||
सत्र ट्रैक करता है कि कौन से चंक सफल हुए।
|
||||
|
||||
**क्लाइंट अपलोड के दौरान डिस्कनेक्ट हो जाता है:**
|
||||
प्राप्त चंक के साथ सत्र कैसेंड्रा में बना रहता है।
|
||||
क्लाइंट यह देखने के लिए `get-upload-status` को कॉल कर सकता है कि क्या गायब है।
|
||||
केवल गायब चंक अपलोड करके फिर से शुरू करें, फिर `complete-upload`।
|
||||
|
||||
**पूर्ण-अपलोड विफलता:**
|
||||
एस3 `CompleteMultipartUpload` परमाणु है - या तो यह पूरी तरह से सफल होता है या विफल रहता है।
|
||||
विफलता पर, भाग बने रहते हैं और क्लाइंट `complete-upload` को फिर से प्रयास कर सकता है।
|
||||
कोई आंशिक दस्तावेज़ कभी भी दिखाई नहीं देता है।
|
||||
|
||||
**सेशन समाप्ति:**
|
||||
कैसेंड्रा TTL 24 घंटे बाद सेशन रिकॉर्ड को हटा देता है।
|
||||
S3 बकेट लाइफसाइकिल पॉलिसी अधूरी मल्टीपार्ट अपलोड को साफ़ करती है।
|
||||
कोई मैनुअल सफाई की आवश्यकता नहीं है।
|
||||
|
||||
### S3 मल्टीपार्ट एटॉमिकिटी
|
||||
|
||||
S3 मल्टीपार्ट अपलोड अंतर्निहित एटॉमिकिटी प्रदान करते हैं:
|
||||
|
||||
1. **भाग अदृश्य होते हैं**: अपलोड किए गए भागों को ऑब्जेक्ट के रूप में एक्सेस नहीं किया जा सकता है।
|
||||
वे केवल एक अधूरी मल्टीपार्ट अपलोड के हिस्से के रूप में मौजूद होते हैं।
|
||||
|
||||
2. **पूर्णता (Atomic completion)**: `CompleteMultipartUpload` या तो सफल होता है (वस्तु परमाणु रूप से दिखाई देती है) या विफल होता है (कोई वस्तु नहीं बनाई जाती है)। कोई आंशिक स्थिति नहीं।
|
||||
|
||||
3. **नाम बदलने की आवश्यकता नहीं**: अंतिम वस्तु कुंजी ⟦CODE_0⟧ समय पर निर्दिष्ट की जाती है। भाग सीधे उस कुंजी पर संयोजित होते हैं।
|
||||
|
||||
`CreateMultipartUpload` समय। भाग सीधे उस कुंजी में संयोजित किए जाते हैं।
|
||||
|
||||
4. **सर्वर-साइड कोएलेसेंस (Server-side coalesce)**: S3 आंतरिक रूप से भागों को जोड़ता है। लाइब्रेरियन
|
||||
कभी भी भागों को वापस नहीं पढ़ता है - दस्तावेज़ के आकार की परवाह किए बिना शून्य मेमोरी ओवरहेड।
|
||||
|
||||
### ब्लबस्टोर एक्सटेंशन (BlobStore Extensions)
|
||||
|
||||
**फ़ाइल:** `trustgraph-flow/trustgraph/librarian/blob_store.py`
|
||||
|
||||
मल्टीपार्ट अपलोड विधियों को जोड़ें:
|
||||
|
||||
```python
|
||||
class BlobStore:
|
||||
# Existing methods...
|
||||
|
||||
def create_multipart_upload(self, object_id: UUID, kind: str) -> str:
|
||||
"""Initialize multipart upload, return s3_upload_id."""
|
||||
# minio client: create_multipart_upload()
|
||||
|
||||
def upload_part(
|
||||
self, object_id: UUID, s3_upload_id: str,
|
||||
part_number: int, data: bytes
|
||||
) -> str:
|
||||
"""Upload a single part, return etag."""
|
||||
# minio client: upload_part()
|
||||
# Note: S3 part numbers are 1-indexed
|
||||
|
||||
def complete_multipart_upload(
|
||||
self, object_id: UUID, s3_upload_id: str,
|
||||
parts: List[Tuple[int, str]] # [(part_number, etag), ...]
|
||||
) -> None:
|
||||
"""Finalize multipart upload."""
|
||||
# minio client: complete_multipart_upload()
|
||||
|
||||
def abort_multipart_upload(
|
||||
self, object_id: UUID, s3_upload_id: str
|
||||
) -> None:
|
||||
"""Cancel multipart upload, clean up parts."""
|
||||
# minio client: abort_multipart_upload()
|
||||
```
|
||||
|
||||
### चंक आकार (Chunk Size) पर विचार
|
||||
|
||||
**S3 न्यूनतम**: प्रति भाग 5MB (अंतिम भाग को छोड़कर)
|
||||
**S3 अधिकतम**: प्रति अपलोड 10,000 भाग
|
||||
**व्यावहारिक डिफ़ॉल्ट**: 5MB के चंक
|
||||
500MB का दस्तावेज़ = 100 चंक
|
||||
5GB का दस्तावेज़ = 1,000 चंक
|
||||
**प्रगति की सूक्ष्मता**: छोटे चंक = अधिक सटीक प्रगति अपडेट
|
||||
**नेटवर्क दक्षता**: बड़े चंक = कम राउंड ट्रिप
|
||||
|
||||
चंक का आकार (5MB - 100MB) की सीमा के भीतर क्लाइंट द्वारा कॉन्फ़िगर किया जा सकता है।
|
||||
|
||||
### दस्तावेज़ प्रसंस्करण: स्ट्रीमिंग पुनर्प्राप्ति
|
||||
|
||||
अपलोड प्रवाह भंडारण में दस्तावेजों को कुशलतापूर्वक लाने के लिए है। प्रसंस्करण प्रवाह दस्तावेजों को पूरी तरह से मेमोरी में लोड किए बिना, उन्हें निकालने और चंक में विभाजित करने के लिए है।
|
||||
|
||||
#### डिज़ाइन सिद्धांत: पहचानकर्ता, सामग्री नहीं
|
||||
|
||||
वर्तमान में, जब प्रसंस्करण शुरू होता है, तो दस्तावेज़ सामग्री पल्सर संदेशों के माध्यम से प्रवाहित होती है। इससे पूरे दस्तावेज़ मेमोरी में लोड हो जाते हैं। इसके बजाय:
|
||||
|
||||
पल्सर संदेश केवल **दस्तावेज़ पहचानकर्ता** ले जाते हैं
|
||||
प्रोसेसर सीधे लाइब्रेरियन से दस्तावेज़ सामग्री प्राप्त करते हैं
|
||||
पुनर्प्राप्ति एक **अस्थायी फ़ाइल में स्ट्रीम** के रूप में होती है
|
||||
दस्तावेज़-विशिष्ट पार्सिंग (PDF, टेक्स्ट, आदि) फ़ाइलों के साथ काम करते हैं, मेमोरी बफ़र्स के साथ नहीं
|
||||
|
||||
यह लाइब्रेरियन को दस्तावेज़-संरचना-अज्ञेयवादी रखता है। PDF पार्सिंग, टेक्स्ट
|
||||
निष्कर्षण और अन्य प्रारूप-विशिष्ट तर्क संबंधित डिकोडर में रहते हैं।
|
||||
|
||||
#### प्रसंस्करण प्रवाह
|
||||
|
||||
|
||||
#### प्रसंस्करण प्रवाह
|
||||
|
||||
```
|
||||
Pulsar PDF Decoder Librarian S3
|
||||
│ │ │ │
|
||||
│── doc-id ───────────►│ │ │
|
||||
│ (processing msg) │ │ │
|
||||
│ │ │ │
|
||||
│ │── stream-document ──────►│ │
|
||||
│ │ (doc-id) │── GetObject ────►│
|
||||
│ │ │ │
|
||||
│ │◄── chunk ────────────────│◄── stream ───────│
|
||||
│ │ (write to temp file) │ │
|
||||
│ │◄── chunk ────────────────│◄── stream ───────│
|
||||
│ │ (append to temp file) │ │
|
||||
│ │ ⋮ │ ⋮ │
|
||||
│ │◄── EOF ──────────────────│ │
|
||||
│ │ │ │
|
||||
│ │ ┌──────────────────────────┐ │
|
||||
│ │ │ temp file on disk │ │
|
||||
│ │ │ (memory stays bounded) │ │
|
||||
│ │ └────────────┬─────────────┘ │
|
||||
│ │ │ │
|
||||
│ │ PDF library opens file │
|
||||
│ │ extract page 1 text ──► chunker │
|
||||
│ │ extract page 2 text ──► chunker │
|
||||
│ │ ⋮ │
|
||||
│ │ close file │
|
||||
│ │ delete temp file │
|
||||
```
|
||||
|
||||
#### लाइब्रेरियन स्ट्रीम एपीआई
|
||||
|
||||
एक स्ट्रीमिंग दस्तावेज़ पुनर्प्राप्ति ऑपरेशन जोड़ें:
|
||||
|
||||
**`stream-document`**
|
||||
|
||||
अनुरोध:
|
||||
```json
|
||||
{
|
||||
"operation": "stream-document",
|
||||
"document-id": "doc-123"
|
||||
}
|
||||
```
|
||||
|
||||
प्रतिक्रिया: स्ट्रीम किए गए बाइनरी खंड (एकल प्रतिक्रिया नहीं)।
|
||||
|
||||
REST API के लिए, यह `Transfer-Encoding: chunked` के साथ एक स्ट्रीमिंग प्रतिक्रिया लौटाता है।
|
||||
|
||||
आंतरिक सेवा-से-सेवा कॉल के लिए (प्रोसेसर से लाइब्रेरियन तक), यह हो सकता है:
|
||||
सीधे प्रीसाइंड URL के माध्यम से S3 स्ट्रीमिंग (यदि आंतरिक नेटवर्क अनुमति देता है)
|
||||
सेवा प्रोटोकॉल पर खंडित प्रतिक्रियाएं
|
||||
एक समर्पित स्ट्रीमिंग एंडपॉइंट
|
||||
|
||||
मुख्य आवश्यकता: डेटा खंडों में प्रवाहित होता है, और कभी भी पूरी तरह से लाइब्रेरियन में बफर नहीं होता है।
|
||||
|
||||
#### PDF डिकोडर परिवर्तन
|
||||
|
||||
**वर्तमान कार्यान्वयन** (मेमोरी-गहन):
|
||||
|
||||
```python
|
||||
def decode_pdf(document_content: bytes) -> str:
|
||||
reader = PdfReader(BytesIO(document_content)) # full doc in memory
|
||||
text = ""
|
||||
for page in reader.pages:
|
||||
text += page.extract_text() # accumulating
|
||||
return text # full text in memory
|
||||
```
|
||||
|
||||
**नया कार्यान्वयन** (अस्थायी फ़ाइल, क्रमिक):
|
||||
|
||||
```python
|
||||
def decode_pdf_streaming(doc_id: str, librarian_client) -> Iterator[str]:
|
||||
"""Yield extracted text page by page."""
|
||||
|
||||
with tempfile.NamedTemporaryFile(delete=True, suffix='.pdf') as tmp:
|
||||
# Stream document to temp file
|
||||
for chunk in librarian_client.stream_document(doc_id):
|
||||
tmp.write(chunk)
|
||||
tmp.flush()
|
||||
|
||||
# Open PDF from file (not memory)
|
||||
reader = PdfReader(tmp.name)
|
||||
|
||||
# Yield pages incrementally
|
||||
for page in reader.pages:
|
||||
yield page.extract_text()
|
||||
|
||||
# tmp file auto-deleted on context exit
|
||||
```
|
||||
|
||||
मेमोरी प्रोफाइल:
|
||||
अस्थायी फ़ाइल डिस्क पर: पीडीएफ का आकार (डिस्क सस्ती है)
|
||||
मेमोरी में: एक बार में एक पृष्ठ का टेक्स्ट
|
||||
अधिकतम मेमोरी: सीमित, दस्तावेज़ के आकार से स्वतंत्र
|
||||
|
||||
#### टेक्स्ट डॉक्यूमेंट डिकोडर में बदलाव
|
||||
|
||||
सादे टेक्स्ट दस्तावेज़ों के लिए, और भी सरल - किसी अस्थायी फ़ाइल की आवश्यकता नहीं:
|
||||
|
||||
```python
|
||||
def decode_text_streaming(doc_id: str, librarian_client) -> Iterator[str]:
|
||||
"""Yield text in chunks as it streams from storage."""
|
||||
|
||||
buffer = ""
|
||||
for chunk in librarian_client.stream_document(doc_id):
|
||||
buffer += chunk.decode('utf-8')
|
||||
|
||||
# Yield complete lines/paragraphs as they arrive
|
||||
while '\n\n' in buffer:
|
||||
paragraph, buffer = buffer.split('\n\n', 1)
|
||||
yield paragraph + '\n\n'
|
||||
|
||||
# Yield remaining buffer
|
||||
if buffer:
|
||||
yield buffer
|
||||
```
|
||||
|
||||
टेक्स्ट दस्तावेज़ सीधे अस्थायी फ़ाइल के बिना स्ट्रीम किए जा सकते हैं क्योंकि वे
|
||||
रैखिक रूप से संरचित होते हैं।
|
||||
|
||||
#### स्ट्रीमिंग चंकर एकीकरण
|
||||
|
||||
चंकर टेक्स्ट (पृष्ठों या पैराग्राफों) का एक इटरेटर प्राप्त करता है और क्रमिक रूप से
|
||||
चंक्स उत्पन्न करता है:
|
||||
|
||||
```python
|
||||
class StreamingChunker:
|
||||
def __init__(self, chunk_size: int, overlap: int):
|
||||
self.chunk_size = chunk_size
|
||||
self.overlap = overlap
|
||||
|
||||
def process(self, text_stream: Iterator[str]) -> Iterator[str]:
|
||||
"""Yield chunks as text arrives."""
|
||||
buffer = ""
|
||||
|
||||
for text_segment in text_stream:
|
||||
buffer += text_segment
|
||||
|
||||
while len(buffer) >= self.chunk_size:
|
||||
chunk = buffer[:self.chunk_size]
|
||||
yield chunk
|
||||
# Keep overlap for context continuity
|
||||
buffer = buffer[self.chunk_size - self.overlap:]
|
||||
|
||||
# Yield remaining buffer as final chunk
|
||||
if buffer.strip():
|
||||
yield buffer
|
||||
```
|
||||
|
||||
#### एंड-टू-एंड प्रोसेसिंग पाइपलाइन
|
||||
|
||||
```python
|
||||
async def process_document(doc_id: str, librarian_client, embedder):
|
||||
"""Process document with bounded memory."""
|
||||
|
||||
# Get document metadata to determine type
|
||||
metadata = await librarian_client.get_document_metadata(doc_id)
|
||||
|
||||
# Select decoder based on document type
|
||||
if metadata.kind == 'application/pdf':
|
||||
text_stream = decode_pdf_streaming(doc_id, librarian_client)
|
||||
elif metadata.kind == 'text/plain':
|
||||
text_stream = decode_text_streaming(doc_id, librarian_client)
|
||||
else:
|
||||
raise UnsupportedDocumentType(metadata.kind)
|
||||
|
||||
# Chunk incrementally
|
||||
chunker = StreamingChunker(chunk_size=1000, overlap=100)
|
||||
|
||||
# Process each chunk as it's produced
|
||||
for chunk in chunker.process(text_stream):
|
||||
# Generate embeddings, store in vector DB, etc.
|
||||
embedding = await embedder.embed(chunk)
|
||||
await store_chunk(doc_id, chunk, embedding)
|
||||
```
|
||||
|
||||
किसी भी समय, संपूर्ण दस्तावेज़ या संपूर्ण निकाले गए पाठ को मेमोरी में संग्रहीत नहीं किया जाता है।
|
||||
|
||||
#### अस्थायी फ़ाइल संबंधी विचार
|
||||
|
||||
**स्थान:** सिस्टम के अस्थायी फ़ोल्डर का उपयोग करें (`/tmp` या समकक्ष)। कंटेनरयुक्त परिनियोजन के लिए, सुनिश्चित करें कि अस्थायी फ़ोल्डर में पर्याप्त जगह है
|
||||
और यह तेज़ स्टोरेज पर है (यदि संभव हो तो नेटवर्क-माउंटेड नहीं)।
|
||||
|
||||
|
||||
**सफाई:** सफाई सुनिश्चित करने के लिए संदर्भ प्रबंधकों (`with tempfile...`) का उपयोग करें
|
||||
यहां तक कि अपवादों पर भी।
|
||||
|
||||
**समवर्ती प्रसंस्करण:** प्रत्येक प्रसंस्करण कार्य का अपना अस्थायी फ़ाइल होता है।
|
||||
समानांतर दस्तावेज़ प्रसंस्करण के बीच कोई टकराव नहीं होता है।
|
||||
|
||||
**डिस्क स्पेस**: अस्थायी फ़ाइलें अल्पकालिक होती हैं (प्रोसेसिंग की अवधि)।
|
||||
500MB के PDF के लिए, प्रोसेसिंग के दौरान 500MB अस्थायी स्थान की आवश्यकता होती है। यदि डिस्क स्पेस सीमित है, तो आकार सीमा अपलोड के समय लागू की जा सकती है।
|
||||
|
||||
|
||||
### एकीकृत प्रोसेसिंग इंटरफ़ेस: चाइल्ड दस्तावेज़
|
||||
|
||||
PDF निष्कर्षण और टेक्स्ट दस्तावेज़ प्रोसेसिंग को एक ही
|
||||
डाउनस्ट्रीम पाइपलाइन (चंकर → एम्बेडिंग → स्टोरेज) में फीड करने की आवश्यकता है। इसे एक सुसंगत "आईडी द्वारा प्राप्त करें" इंटरफ़ेस के साथ प्राप्त करने के लिए, निकाले गए टेक्स्ट ब्लॉकों को "चाइल्ड दस्तावेज़" के रूप में लाइब्रेरियन में वापस संग्रहीत किया जाता है।
|
||||
|
||||
|
||||
|
||||
#### चाइल्ड दस्तावेज़ों के साथ प्रोसेसिंग प्रवाह
|
||||
|
||||
```
|
||||
PDF Document Text Document
|
||||
│ │
|
||||
▼ │
|
||||
pdf-extractor │
|
||||
│ │
|
||||
│ (stream PDF from librarian) │
|
||||
│ (extract page 1 text) │
|
||||
│ (store as child doc → librarian) │
|
||||
│ (extract page 2 text) │
|
||||
│ (store as child doc → librarian) │
|
||||
│ ⋮ │
|
||||
▼ ▼
|
||||
[child-doc-id, child-doc-id, ...] [doc-id]
|
||||
│ │
|
||||
└─────────────────────┬───────────────────────────────┘
|
||||
▼
|
||||
chunker
|
||||
│
|
||||
│ (receives document ID)
|
||||
│ (streams content from librarian)
|
||||
│ (chunks incrementally)
|
||||
▼
|
||||
[chunks → embedding → storage]
|
||||
```
|
||||
|
||||
चंकर (chunker) में एक समान इंटरफ़ेस है:
|
||||
एक दस्तावेज़ आईडी प्राप्त करें (पल्सर के माध्यम से)
|
||||
लाइब्रेरियन से सामग्री स्ट्रीम करें
|
||||
इसे छोटे भागों में विभाजित करें
|
||||
|
||||
यह नहीं जानता या परवाह नहीं करता कि आईडी किस चीज़ को संदर्भित करती है:
|
||||
एक उपयोगकर्ता द्वारा अपलोड किया गया टेक्स्ट दस्तावेज़
|
||||
एक पीडीएफ पृष्ठ से निकाला गया टेक्स्ट ब्लॉक
|
||||
कोई भी भविष्य का दस्तावेज़ प्रकार
|
||||
|
||||
#### चाइल्ड दस्तावेज़ मेटाडेटा
|
||||
|
||||
दस्तावेज़ स्कीमा को पैरेंट/चाइल्ड संबंधों को ट्रैक करने के लिए विस्तारित करें:
|
||||
|
||||
```sql
|
||||
-- Add columns to document table
|
||||
ALTER TABLE document ADD parent_id text;
|
||||
ALTER TABLE document ADD document_type text;
|
||||
|
||||
-- Index for finding children of a parent
|
||||
CREATE INDEX document_parent ON document (parent_id);
|
||||
```
|
||||
|
||||
**दस्तावेज़ के प्रकार:**
|
||||
|
||||
| `document_type` | विवरण |
|
||||
|-----------------|-------------|
|
||||
| `source` | उपयोगकर्ता द्वारा अपलोड किया गया दस्तावेज़ (पीडीएफ, टेक्स्ट, आदि) |
|
||||
| `extracted` | स्रोत दस्तावेज़ से प्राप्त (उदाहरण के लिए, पीडीएफ पृष्ठ पाठ) |
|
||||
|
||||
**मेटाडेटा फ़ील्ड:**
|
||||
|
||||
| फ़ील्ड | स्रोत दस्तावेज़ | निकाली गई चाइल्ड |
|
||||
|-------|-----------------|-----------------|
|
||||
| `id` | उपयोगकर्ता द्वारा प्रदान किया गया या उत्पन्न | उत्पन्न (उदाहरण के लिए, `{parent-id}-page-{n}`) |
|
||||
| `parent_id` | `NULL` | मूल दस्तावेज़ आईडी |
|
||||
| `document_type` | `source` | `extracted` |
|
||||
| `kind` | `application/pdf`, आदि | `text/plain` |
|
||||
| `title` | उपयोगकर्ता द्वारा प्रदान किया गया | उत्पन्न (उदाहरण के लिए, "रिपोर्ट.pdf का पृष्ठ 3") |
|
||||
| `user` | प्रमाणित उपयोगकर्ता | मूल के समान |
|
||||
|
||||
#### चाइल्ड दस्तावेज़ों के लिए लाइब्रेरियन एपीआई
|
||||
|
||||
**चाइल्ड दस्तावेज़ बनाना** (आंतरिक, pdf-extractor द्वारा उपयोग किया जाता है):
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": "add-child-document",
|
||||
"parent-id": "doc-123",
|
||||
"document-metadata": {
|
||||
"id": "doc-123-page-1",
|
||||
"kind": "text/plain",
|
||||
"title": "Page 1"
|
||||
},
|
||||
"content": "<base64-encoded-text>"
|
||||
}
|
||||
```
|
||||
|
||||
छोटे, निकाले गए टेक्स्ट के लिए (सामान्य पृष्ठ टेक्स्ट < 100KB है), सिंगल-ऑपरेशन अपलोड स्वीकार्य है। बहुत बड़े टेक्स्ट एक्सट्रैक्शन के लिए, चंक्ड अपलोड का उपयोग किया जा सकता है।
|
||||
|
||||
**चाइल्ड दस्तावेज़ों की सूची** (डीबगिंग/एडमिन के लिए):
|
||||
|
||||
**चाइल्ड दस्तावेज़ों की सूची** (डीबगिंग/प्रशासन के लिए):
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": "list-children",
|
||||
"parent-id": "doc-123"
|
||||
}
|
||||
```
|
||||
|
||||
प्रतिक्रिया:
|
||||
```json
|
||||
{
|
||||
"children": [
|
||||
{ "id": "doc-123-page-1", "title": "Page 1", "kind": "text/plain" },
|
||||
{ "id": "doc-123-page-2", "title": "Page 2", "kind": "text/plain" },
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### उपयोगकर्ता-सामना करने वाला व्यवहार
|
||||
|
||||
**`list-documents` डिफ़ॉल्ट व्यवहार:**
|
||||
|
||||
```sql
|
||||
SELECT * FROM document WHERE user = ? AND parent_id IS NULL;
|
||||
```
|
||||
|
||||
केवल शीर्ष-स्तरीय (मूल) दस्तावेज़ ही उपयोगकर्ता की दस्तावेज़ सूची में दिखाई देते हैं।
|
||||
चाइल्ड दस्तावेज़ डिफ़ॉल्ट रूप से फ़िल्टर कर दिए जाते हैं।
|
||||
|
||||
**वैकल्पिक 'शामिल-चाइल्ड' फ़्लैग** (व्यवस्थापक/डीबगिंग के लिए):
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": "list-documents",
|
||||
"include-children": true
|
||||
}
|
||||
```
|
||||
|
||||
#### कैस्केड डिलीट
|
||||
|
||||
जब कोई पैरेंट दस्तावेज़ हटाया जाता है, तो सभी चाइल्ड दस्तावेज़ों को भी हटाया जाना चाहिए:
|
||||
|
||||
```python
|
||||
def delete_document(doc_id: str):
|
||||
# Find all children
|
||||
children = query("SELECT id, object_id FROM document WHERE parent_id = ?", doc_id)
|
||||
|
||||
# Delete child blobs from S3
|
||||
for child in children:
|
||||
blob_store.delete(child.object_id)
|
||||
|
||||
# Delete child metadata from Cassandra
|
||||
execute("DELETE FROM document WHERE parent_id = ?", doc_id)
|
||||
|
||||
# Delete parent blob and metadata
|
||||
parent = get_document(doc_id)
|
||||
blob_store.delete(parent.object_id)
|
||||
execute("DELETE FROM document WHERE id = ? AND user = ?", doc_id, user)
|
||||
```
|
||||
|
||||
#### भंडारण संबंधी विचार
|
||||
|
||||
निकाले गए टेक्स्ट ब्लॉक डुप्लिकेट सामग्री बनाते हैं:
|
||||
मूल पीडीएफ "गैराज" में संग्रहीत है।
|
||||
प्रत्येक पृष्ठ के लिए निकाला गया टेक्स्ट भी "गैराज" में संग्रहीत है।
|
||||
|
||||
यह समझौता निम्नलिखित को सक्षम बनाता है:
|
||||
**समान चंकर इंटरफ़ेस**: चंकर हमेशा आईडी द्वारा डेटा प्राप्त करता है।
|
||||
**फिर से शुरू/पुनः प्रयास**: पीडीएफ को फिर से निकालने के बिना, चंकर चरण पर पुनः आरंभ किया जा सकता है।
|
||||
**डीबगिंग**: निकाले गए टेक्स्ट का निरीक्षण किया जा सकता है।
|
||||
**चिंताओं का पृथक्करण**: पीडीएफ एक्सट्रैक्टर और चंकर स्वतंत्र सेवाएं हैं।
|
||||
|
||||
500 एमबी के पीडीएफ में 200 पृष्ठ हैं, जिनमें से प्रत्येक पृष्ठ पर औसतन 5 केबी टेक्स्ट है:
|
||||
पीडीएफ भंडारण: 500 एमबी
|
||||
निकाले गए टेक्स्ट भंडारण: लगभग 1 एमबी
|
||||
अतिरिक्त भार: नगण्य
|
||||
|
||||
#### पीडीएफ एक्सट्रैक्टर आउटपुट
|
||||
|
||||
पीडीएफ-एक्सट्रैक्टर, किसी दस्तावेज़ को संसाधित करने के बाद:
|
||||
|
||||
1. पीडीएफ को लाइब्रेरियन से अस्थायी फ़ाइल में स्ट्रीम करता है।
|
||||
2. पृष्ठ दर पृष्ठ टेक्स्ट निकालता है।
|
||||
3. प्रत्येक पृष्ठ के लिए, निकाले गए टेक्स्ट को लाइब्रेरियन के माध्यम से एक चाइल्ड दस्तावेज़ के रूप में संग्रहीत करता है।
|
||||
4. चाइल्ड दस्तावेज़ आईडी को चंकर कतार में भेजता है।
|
||||
|
||||
```python
|
||||
async def extract_pdf(doc_id: str, librarian_client, output_queue):
|
||||
"""Extract PDF pages and store as child documents."""
|
||||
|
||||
with tempfile.NamedTemporaryFile(delete=True, suffix='.pdf') as tmp:
|
||||
# Stream PDF to temp file
|
||||
for chunk in librarian_client.stream_document(doc_id):
|
||||
tmp.write(chunk)
|
||||
tmp.flush()
|
||||
|
||||
# Extract pages
|
||||
reader = PdfReader(tmp.name)
|
||||
for page_num, page in enumerate(reader.pages, start=1):
|
||||
text = page.extract_text()
|
||||
|
||||
# Store as child document
|
||||
child_id = f"{doc_id}-page-{page_num}"
|
||||
await librarian_client.add_child_document(
|
||||
parent_id=doc_id,
|
||||
document_id=child_id,
|
||||
kind="text/plain",
|
||||
title=f"Page {page_num}",
|
||||
content=text.encode('utf-8')
|
||||
)
|
||||
|
||||
# Send to chunker queue
|
||||
await output_queue.send(child_id)
|
||||
```
|
||||
|
||||
चंकर इन चाइल्ड आईडी को प्राप्त करता है और उन्हें उसी तरह संसाधित करता है जैसे कि वह किसी उपयोगकर्ता द्वारा अपलोड किए गए टेक्स्ट दस्तावेज़ को संसाधित करता है।
|
||||
चंकर इन चाइल्ड आईडी को प्राप्त करता है और उन्हें उसी तरह संसाधित करता है जैसे कि वह किसी उपयोगकर्ता द्वारा अपलोड किए गए टेक्स्ट दस्तावेज़ को संसाधित करता है।
|
||||
|
||||
### क्लाइंट अपडेट
|
||||
|
||||
#### पायथन एसडीके
|
||||
|
||||
पायथन एसडीके (`trustgraph-base/trustgraph/api/library.py`) को खंडित अपलोड को पारदर्शी रूप से संभालना चाहिए। सार्वजनिक इंटरफ़ेस अपरिवर्तित रहता है:
|
||||
खंडित अपलोड को पारदर्शी रूप से संभालना चाहिए। सार्वजनिक इंटरफ़ेस अपरिवर्तित रहता है:
|
||||
|
||||
```python
|
||||
# Existing interface - no change for users
|
||||
library.add_document(
|
||||
id="doc-123",
|
||||
title="Large Report",
|
||||
kind="application/pdf",
|
||||
content=large_pdf_bytes, # Can be hundreds of MB
|
||||
tags=["reports"]
|
||||
)
|
||||
```
|
||||
|
||||
आंतरिक रूप से, SDK दस्तावेज़ के आकार का पता लगाता है और रणनीति बदलता है:
|
||||
|
||||
```python
|
||||
class Library:
|
||||
CHUNKED_UPLOAD_THRESHOLD = 2 * 1024 * 1024 # 2MB
|
||||
|
||||
def add_document(self, id, title, kind, content, tags=None, ...):
|
||||
if len(content) < self.CHUNKED_UPLOAD_THRESHOLD:
|
||||
# Small document: single operation (existing behavior)
|
||||
return self._add_document_single(id, title, kind, content, tags)
|
||||
else:
|
||||
# Large document: chunked upload
|
||||
return self._add_document_chunked(id, title, kind, content, tags)
|
||||
|
||||
def _add_document_chunked(self, id, title, kind, content, tags):
|
||||
# 1. begin-upload
|
||||
session = self._begin_upload(
|
||||
document_metadata={...},
|
||||
total_size=len(content),
|
||||
chunk_size=5 * 1024 * 1024
|
||||
)
|
||||
|
||||
# 2. upload-chunk for each chunk
|
||||
for i, chunk in enumerate(self._chunk_bytes(content, session.chunk_size)):
|
||||
self._upload_chunk(session.upload_id, i, chunk)
|
||||
|
||||
# 3. complete-upload
|
||||
return self._complete_upload(session.upload_id)
|
||||
```
|
||||
|
||||
**प्रगति कॉलबैक** (वैकल्पिक संवर्द्धन):
|
||||
|
||||
```python
|
||||
def add_document(self, ..., on_progress=None):
|
||||
"""
|
||||
on_progress: Optional callback(bytes_sent, total_bytes)
|
||||
"""
|
||||
```
|
||||
|
||||
यह यूआई को बुनियादी एपीआई को बदले बिना अपलोड की प्रगति प्रदर्शित करने की अनुमति देता है।
|
||||
|
||||
#### कमांड लाइन उपकरण
|
||||
|
||||
**`tg-add-library-document`** बिना किसी बदलाव के काम करता रहता है:
|
||||
|
||||
```bash
|
||||
# Works transparently for any size - SDK handles chunking internally
|
||||
tg-add-library-document --file large-report.pdf --title "Large Report"
|
||||
```
|
||||
|
||||
वैकल्पिक प्रगति प्रदर्शन जोड़ा जा सकता है:
|
||||
|
||||
```bash
|
||||
tg-add-library-document --file large-report.pdf --title "Large Report" --progress
|
||||
# Output:
|
||||
# Uploading: 45% (225MB / 500MB)
|
||||
```
|
||||
|
||||
**पुराने उपकरण हटा दिए गए:**
|
||||
|
||||
`tg-load-pdf` - अप्रचलित, `tg-add-library-document` का उपयोग करें।
|
||||
`tg-load-text` - अप्रचलित, `tg-add-library-document` का उपयोग करें।
|
||||
|
||||
**व्यवस्थापक/डीबग कमांड** (वैकल्पिक, कम प्राथमिकता):
|
||||
|
||||
```bash
|
||||
# List incomplete uploads (admin troubleshooting)
|
||||
tg-add-library-document --list-pending
|
||||
|
||||
# Resume specific upload (recovery scenario)
|
||||
tg-add-library-document --resume upload-abc-123 --file large-report.pdf
|
||||
```
|
||||
|
||||
ये मौजूदा कमांड पर मौजूद फ़्लैग हो सकते हैं, अलग-अलग टूल नहीं।
|
||||
|
||||
#### एपीआई विनिर्देश अपडेट
|
||||
|
||||
OpenAPI विनिर्देश (`specs/api/paths/librarian.yaml`) को निम्नलिखित के लिए अपडेट करने की आवश्यकता है:
|
||||
|
||||
**नए ऑपरेशन:**
|
||||
|
||||
`begin-upload` - चंक्ड अपलोड सत्र को आरंभ करें
|
||||
`upload-chunk` - व्यक्तिगत चंक अपलोड करें
|
||||
`complete-upload` - अपलोड को अंतिम रूप दें
|
||||
`abort-upload` - अपलोड को रद्द करें
|
||||
`get-upload-status` - अपलोड की प्रगति की जांच करें
|
||||
`list-uploads` - उपयोगकर्ता के लिए अपूर्ण अपलोड की सूची बनाएं
|
||||
`stream-document` - दस्तावेज़ पुनर्प्राप्ति (स्ट्रीमिंग)
|
||||
`add-child-document` - निकाले गए पाठ को संग्रहीत करें (आंतरिक)
|
||||
`list-children` - चाइल्ड दस्तावेज़ों की सूची बनाएं (व्यवस्थापक)
|
||||
|
||||
**संशोधित ऑपरेशन:**
|
||||
|
||||
`list-documents` - `include-children` पैरामीटर जोड़ें
|
||||
|
||||
**नए स्कीमा:**
|
||||
|
||||
`ChunkedUploadBeginRequest`
|
||||
`ChunkedUploadBeginResponse`
|
||||
`ChunkedUploadChunkRequest`
|
||||
`ChunkedUploadChunkResponse`
|
||||
`UploadSession`
|
||||
`UploadProgress`
|
||||
|
||||
**WebSocket विनिर्देश अपडेट** (`specs/websocket/`):
|
||||
|
||||
WebSocket क्लाइंट के लिए REST ऑपरेशन को प्रतिबिंबित करें, जिससे अपलोड के दौरान वास्तविक समय
|
||||
प्रगति अपडेट सक्षम हो सके।
|
||||
|
||||
#### यूएक्स विचार
|
||||
|
||||
एपीआई विनिर्देश अपडेट फ्रंटएंड में सुधारों को सक्षम करते हैं:
|
||||
|
||||
**अपलोड प्रगति यूआई:**
|
||||
अपलोड किए गए चंक्स को दिखाने वाला प्रगति बार
|
||||
अनुमानित शेष समय
|
||||
पॉज़/रीज़्यूम क्षमता
|
||||
|
||||
**त्रुटि सुधार:**
|
||||
बाधित अपलोड के लिए "अपलोड फिर से शुरू करें" विकल्प
|
||||
पुनः कनेक्ट करने पर लंबित अपलोड की सूची
|
||||
|
||||
**बड़ी फ़ाइल हैंडलिंग:**
|
||||
क्लाइंट-साइड फ़ाइल आकार का पता लगाना
|
||||
बड़ी फ़ाइलों के लिए स्वचालित चंक्ड अपलोड
|
||||
लंबे अपलोड के दौरान स्पष्ट प्रतिक्रिया
|
||||
|
||||
ये यूएक्स सुधार अपडेट किए गए एपीआई विनिर्देश द्वारा निर्देशित फ्रंटएंड कार्य की आवश्यकता है।
|
||||
358
docs/tech-specs/hi/logging-strategy.hi.md
Normal file
358
docs/tech-specs/hi/logging-strategy.hi.md
Normal file
|
|
@ -0,0 +1,358 @@
|
|||
---
|
||||
layout: default
|
||||
title: "ट्रस्टग्राफ लॉगिंग रणनीति"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# ट्रस्टग्राफ लॉगिंग रणनीति
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
ट्रस्टग्राफ सभी लॉगिंग कार्यों के लिए पायथन के अंतर्निहित `logging` मॉड्यूल का उपयोग करता है, जिसमें केंद्रीकृत कॉन्फ़िगरेशन और लॉग एकत्रीकरण के लिए वैकल्पिक लोकी एकीकरण शामिल है। यह सिस्टम के सभी घटकों में लॉगिंग के लिए एक मानकीकृत, लचीला दृष्टिकोण प्रदान करता है।
|
||||
|
||||
## डिफ़ॉल्ट कॉन्फ़िगरेशन
|
||||
|
||||
### लॉगिंग स्तर
|
||||
**डिफ़ॉल्ट स्तर**: `INFO`
|
||||
**कॉन्फ़िगरेशन**: `--log-level` कमांड-लाइन तर्क के माध्यम से
|
||||
**विकल्प**: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
|
||||
|
||||
### आउटपुट गंतव्य
|
||||
1. **कंसोल (stdout)**: हमेशा सक्षम - कंटेनरीकृत वातावरणों के साथ संगतता सुनिश्चित करता है
|
||||
2. **लोकी**: वैकल्पिक केंद्रीकृत लॉग एकत्रीकरण (डिफ़ॉल्ट रूप से सक्षम, इसे अक्षम किया जा सकता है)
|
||||
|
||||
## केंद्रीकृत लॉगिंग मॉड्यूल
|
||||
|
||||
सभी लॉगिंग कॉन्फ़िगरेशन को `trustgraph.base.logging` मॉड्यूल द्वारा प्रबंधित किया जाता है, जो निम्नलिखित प्रदान करता है:
|
||||
`add_logging_args(parser)` - मानक लॉगिंग CLI तर्क जोड़ता है
|
||||
`setup_logging(args)` - पार्स किए गए तर्कों से लॉगिंग को कॉन्फ़िगर करता है
|
||||
|
||||
इस मॉड्यूल का उपयोग सभी सर्वर-साइड घटकों द्वारा किया जाता है:
|
||||
AsyncProcessor-आधारित सेवाएं
|
||||
एपीआई गेटवे
|
||||
एमसीपी सर्वर
|
||||
|
||||
## कार्यान्वयन दिशानिर्देश
|
||||
|
||||
### 1. लॉगर इनिशियलाइज़ेशन
|
||||
|
||||
प्रत्येक मॉड्यूल को मॉड्यूल के `__name__` का उपयोग करके अपना लॉगर बनाना चाहिए:
|
||||
|
||||
```python
|
||||
import logging
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
```
|
||||
|
||||
लॉगर का नाम स्वचालित रूप से लोकी में फ़िल्टरिंग और खोज के लिए एक लेबल के रूप में उपयोग किया जाता है।
|
||||
|
||||
### 2. सेवा आरंभिकरण
|
||||
|
||||
सभी सर्वर-साइड सेवाओं को केंद्रीकृत मॉड्यूल के माध्यम से स्वचालित रूप से लॉगिंग कॉन्फ़िगरेशन प्राप्त होता है:
|
||||
|
||||
```python
|
||||
from trustgraph.base import add_logging_args, setup_logging
|
||||
import argparse
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser()
|
||||
|
||||
# Add standard logging arguments (includes Loki configuration)
|
||||
add_logging_args(parser)
|
||||
|
||||
# Add your service-specific arguments
|
||||
parser.add_argument('--port', type=int, default=8080)
|
||||
|
||||
args = parser.parse_args()
|
||||
args = vars(args)
|
||||
|
||||
# Setup logging early in startup
|
||||
setup_logging(args)
|
||||
|
||||
# Rest of your service initialization
|
||||
logger = logging.getLogger(__name__)
|
||||
logger.info("Service starting...")
|
||||
```
|
||||
|
||||
### 3. कमांड-लाइन तर्क
|
||||
|
||||
सभी सेवाएं इन लॉगिंग तर्कों का समर्थन करती हैं:
|
||||
|
||||
**लॉग स्तर:**
|
||||
```bash
|
||||
--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
|
||||
```
|
||||
|
||||
**लोकी कॉन्फ़िगरेशन:**
|
||||
```bash
|
||||
--loki-enabled # Enable Loki (default)
|
||||
--no-loki-enabled # Disable Loki
|
||||
--loki-url URL # Loki push URL (default: http://loki:3100/loki/api/v1/push)
|
||||
--loki-username USERNAME # Optional authentication
|
||||
--loki-password PASSWORD # Optional authentication
|
||||
```
|
||||
|
||||
**उदाहरण:**
|
||||
```bash
|
||||
# Default - INFO level, Loki enabled
|
||||
./my-service
|
||||
|
||||
# Debug mode, console only
|
||||
./my-service --log-level DEBUG --no-loki-enabled
|
||||
|
||||
# Custom Loki server with auth
|
||||
./my-service --loki-url http://loki.prod:3100/loki/api/v1/push \
|
||||
--loki-username admin --loki-password secret
|
||||
```
|
||||
|
||||
### 4. पर्यावरण चर
|
||||
|
||||
लोकी कॉन्फ़िगरेशन पर्यावरण चर के उपयोग का समर्थन करता है:
|
||||
|
||||
```bash
|
||||
export LOKI_URL=http://loki.prod:3100/loki/api/v1/push
|
||||
export LOKI_USERNAME=admin
|
||||
export LOKI_PASSWORD=secret
|
||||
```
|
||||
|
||||
कमांड-लाइन तर्क पर्यावरण चर से अधिक महत्वपूर्ण होते हैं।
|
||||
|
||||
### 5. लॉगिंग के सर्वोत्तम अभ्यास
|
||||
|
||||
#### लॉग स्तरों का उपयोग
|
||||
**DEBUG**: समस्याओं के निदान के लिए विस्तृत जानकारी (चर मान, फ़ंक्शन प्रविष्टि/निकास)
|
||||
**INFO**: सामान्य सूचनात्मक संदेश (सेवा शुरू, कॉन्फ़िगरेशन लोड, प्रसंस्करण मील के पत्थर)
|
||||
**WARNING**: संभावित रूप से हानिकारक स्थितियों के लिए चेतावनी संदेश (अप्रचलित सुविधाएँ, ठीक होने योग्य त्रुटियाँ)
|
||||
**ERROR**: गंभीर समस्याओं के लिए त्रुटि संदेश (विफल संचालन, अपवाद)
|
||||
**CRITICAL**: तत्काल ध्यान देने की आवश्यकता वाले सिस्टम विफलताओं के लिए महत्वपूर्ण संदेश
|
||||
|
||||
#### संदेश प्रारूप
|
||||
```python
|
||||
# Good - includes context
|
||||
logger.info(f"Processing document: {doc_id}, size: {doc_size} bytes")
|
||||
logger.error(f"Failed to connect to database: {error}", exc_info=True)
|
||||
|
||||
# Avoid - lacks context
|
||||
logger.info("Processing document")
|
||||
logger.error("Connection failed")
|
||||
```
|
||||
|
||||
#### प्रदर्शन संबंधी विचार
|
||||
```python
|
||||
# Use lazy formatting for expensive operations
|
||||
logger.debug("Expensive operation result: %s", expensive_function())
|
||||
|
||||
# Check log level for very expensive debug operations
|
||||
if logger.isEnabledFor(logging.DEBUG):
|
||||
debug_data = compute_expensive_debug_info()
|
||||
logger.debug(f"Debug data: {debug_data}")
|
||||
```
|
||||
|
||||
### 6. लोकी के साथ संरचित लॉगिंग
|
||||
|
||||
जटिल डेटा के लिए, लोकी के लिए अतिरिक्त टैग के साथ संरचित लॉगिंग का उपयोग करें:
|
||||
|
||||
```python
|
||||
logger.info("Request processed", extra={
|
||||
'tags': {
|
||||
'request_id': request_id,
|
||||
'user_id': user_id,
|
||||
'status': 'success'
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
ये टैग, स्वचालित लेबल के अतिरिक्त, लोकी में खोज योग्य लेबल बन जाते हैं:
|
||||
`severity` - लॉग स्तर (डीबग, जानकारी, चेतावनी, त्रुटि, गंभीर)
|
||||
`logger` - मॉड्यूल का नाम (`__name__` से)
|
||||
|
||||
### 7. अपवाद लॉगिंग
|
||||
|
||||
हमेशा अपवादों के लिए स्टैक ट्रेस शामिल करें:
|
||||
|
||||
```python
|
||||
try:
|
||||
process_data()
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to process data: {e}", exc_info=True)
|
||||
raise
|
||||
```
|
||||
|
||||
### 8. एसिंक्रोनस लॉगिंग संबंधी विचार
|
||||
|
||||
लॉगिंग सिस्टम लोकी के लिए गैर-ब्लॉकिंग कतार वाले हैंडलर का उपयोग करता है:
|
||||
कंसोल आउटपुट सिंक्रोनस (तेज़) है
|
||||
लोकी आउटपुट 500-संदेश बफर के साथ कतारबद्ध है
|
||||
बैकग्राउंड थ्रेड लोकी ट्रांसमिशन को संभालता है
|
||||
मुख्य एप्लिकेशन कोड का कोई अवरोधन नहीं
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
import logging
|
||||
|
||||
async def async_operation():
|
||||
logger = logging.getLogger(__name__)
|
||||
# Logging is thread-safe and won't block async operations
|
||||
logger.info(f"Starting async operation in task: {asyncio.current_task().get_name()}")
|
||||
```
|
||||
|
||||
## लोकी एकीकरण
|
||||
|
||||
### वास्तुकला
|
||||
|
||||
लॉगिंग सिस्टम, गैर-अवरुद्ध लोकी एकीकरण के लिए पायथन के अंतर्निहित `QueueHandler` और `QueueListener` का उपयोग करता है:
|
||||
|
||||
1. **क्यू हैंडलर**: लॉग को 500 संदेशों की कतार में रखा जाता है (गैर-अवरुद्ध)।
|
||||
2. **बैकग्राउंड थ्रेड**: क्यू लिसनर एसिंक्रोनस रूप से लोकी को लॉग भेजता है।
|
||||
3. **सुगम गिरावट**: यदि लोकी अनुपलब्ध है, तो कंसोल लॉगिंग जारी रहती है।
|
||||
|
||||
### स्वचालित लेबल
|
||||
|
||||
लोकी को भेजे गए प्रत्येक लॉग में शामिल हैं:
|
||||
`processor`: प्रोसेसर पहचान (उदाहरण के लिए, `config-svc`, `text-completion`, `embeddings`)
|
||||
`severity`: लॉग स्तर (डीबग, जानकारी, आदि)
|
||||
`logger`: मॉड्यूल नाम (उदाहरण के लिए, `trustgraph.gateway.service`, `trustgraph.agent.react.service`)
|
||||
|
||||
### कस्टम लेबल
|
||||
|
||||
`extra` पैरामीटर के माध्यम से कस्टम लेबल जोड़ें:
|
||||
|
||||
```python
|
||||
logger.info("User action", extra={
|
||||
'tags': {
|
||||
'user_id': user_id,
|
||||
'action': 'document_upload',
|
||||
'collection': collection_name
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### लोकी में लॉग की खोज
|
||||
|
||||
```logql
|
||||
# All logs from a specific processor (recommended - matches Prometheus metrics)
|
||||
{processor="config-svc"}
|
||||
{processor="text-completion"}
|
||||
{processor="embeddings"}
|
||||
|
||||
# Error logs from a specific processor
|
||||
{processor="config-svc", severity="ERROR"}
|
||||
|
||||
# Error logs from all processors
|
||||
{severity="ERROR"}
|
||||
|
||||
# Logs from a specific processor with text filter
|
||||
{processor="text-completion"} |= "Processing"
|
||||
|
||||
# All logs from API gateway
|
||||
{processor="api-gateway"}
|
||||
|
||||
# Logs from processors matching pattern
|
||||
{processor=~".*-completion"}
|
||||
|
||||
# Logs with custom tags
|
||||
{processor="api-gateway"} | json | user_id="12345"
|
||||
```
|
||||
|
||||
### सुचारू रूप से कार्यक्षमता में कमी
|
||||
|
||||
यदि लोकी अनुपलब्ध है या `python-logging-loki` स्थापित नहीं है:
|
||||
कंसोल पर चेतावनी संदेश प्रदर्शित किया जाता है
|
||||
कंसोल लॉगिंग सामान्य रूप से जारी रहता है
|
||||
एप्लिकेशन चलता रहता है
|
||||
लोकी कनेक्शन के लिए कोई पुनः प्रयास तर्क नहीं (तुरंत विफल, सुचारू रूप से कार्यक्षमता में कमी)
|
||||
|
||||
## परीक्षण
|
||||
|
||||
परीक्षण के दौरान, एक अलग लॉगिंग कॉन्फ़िगरेशन का उपयोग करने पर विचार करें:
|
||||
|
||||
```python
|
||||
# In test setup
|
||||
import logging
|
||||
|
||||
# Reduce noise during tests
|
||||
logging.getLogger().setLevel(logging.WARNING)
|
||||
|
||||
# Or disable Loki for tests
|
||||
setup_logging({'log_level': 'WARNING', 'loki_enabled': False})
|
||||
```
|
||||
|
||||
## निगरानी एकीकरण
|
||||
|
||||
### मानक प्रारूप
|
||||
सभी लॉग एक सुसंगत प्रारूप का उपयोग करते हैं:
|
||||
```
|
||||
2025-01-09 10:30:45,123 - trustgraph.gateway.service - INFO - Request processed
|
||||
```
|
||||
|
||||
प्रारूप घटक:
|
||||
टाइमस्टैम्प (मिलीसेकंड के साथ आईएसओ प्रारूप)
|
||||
लॉगर नाम (मॉड्यूल पथ)
|
||||
लॉग स्तर
|
||||
संदेश
|
||||
|
||||
### निगरानी के लिए लोकी प्रश्न
|
||||
|
||||
सामान्य निगरानी प्रश्न:
|
||||
|
||||
```logql
|
||||
# Error rate by processor
|
||||
rate({severity="ERROR"}[5m]) by (processor)
|
||||
|
||||
# Top error-producing processors
|
||||
topk(5, count_over_time({severity="ERROR"}[1h]) by (processor))
|
||||
|
||||
# Recent errors with processor name
|
||||
{severity="ERROR"} | line_format "{{.processor}}: {{.message}}"
|
||||
|
||||
# All agent processors
|
||||
{processor=~".*agent.*"} |= "exception"
|
||||
|
||||
# Specific processor error count
|
||||
count_over_time({processor="config-svc", severity="ERROR"}[1h])
|
||||
```
|
||||
|
||||
## सुरक्षा संबंधी विचार
|
||||
|
||||
**कभी भी संवेदनशील जानकारी लॉग न करें** (पासवर्ड, एपीआई कुंजियाँ, व्यक्तिगत डेटा, टोकन)
|
||||
लॉगिंग से पहले **उपयोगकर्ता इनपुट को साफ़ करें**
|
||||
संवेदनशील फ़ील्ड के लिए **प्लेसहोल्डर का उपयोग करें**: `user_id=****1234`
|
||||
**लोकी प्रमाणीकरण**: सुरक्षित परिनियोजन के लिए `--loki-username` और `--loki-password` का उपयोग करें
|
||||
**सुरक्षित परिवहन**: उत्पादन में लोकी यूआरएल के लिए HTTPS का उपयोग करें: `https://loki.prod:3100/loki/api/v1/push`
|
||||
|
||||
## निर्भरताएँ
|
||||
|
||||
केंद्रीकृत लॉगिंग मॉड्यूल को निम्नलिखित की आवश्यकता है:
|
||||
`python-logging-loki` - लोकी एकीकरण के लिए (वैकल्पिक, यदि अनुपलब्ध हो तो सुचारू गिरावट)
|
||||
|
||||
पहले से ही `trustgraph-base/pyproject.toml` और `requirements.txt` में शामिल है।
|
||||
|
||||
## माइग्रेशन पथ
|
||||
|
||||
मौजूदा कोड के लिए:
|
||||
|
||||
1. **AsyncProcessor का उपयोग कर रहे सेवाएँ**: कोई बदलाव आवश्यक नहीं, लोकी समर्थन स्वचालित है
|
||||
2. **AsyncProcessor का उपयोग नहीं कर रही सेवाएँ** (api-gateway, mcp-server): पहले से ही अपडेट किया गया है
|
||||
3. **CLI उपकरण**: दायरे से बाहर - print() या साधारण लॉगिंग का उपयोग जारी रखें
|
||||
|
||||
### print() से लॉगिंग तक:
|
||||
```python
|
||||
# Before
|
||||
print(f"Processing document {doc_id}")
|
||||
|
||||
# After
|
||||
logger = logging.getLogger(__name__)
|
||||
logger.info(f"Processing document {doc_id}")
|
||||
```
|
||||
|
||||
## कॉन्फ़िगरेशन सारांश
|
||||
|
||||
| तर्क | डिफ़ॉल्ट | पर्यावरण चर | विवरण |
|
||||
|----------|---------|---------------------|-------------|
|
||||
| `--log-level` | `INFO` | - | कंसोल और लोकी लॉग स्तर |
|
||||
| `--loki-enabled` | `True` | - | लोकी लॉगिंग सक्षम करें |
|
||||
| `--loki-url` | `http://loki:3100/loki/api/v1/push` | `LOKI_URL` | लोकी पुश एंडपॉइंट |
|
||||
| `--loki-username` | `None` | `LOKI_USERNAME` | लोकी ऑथ उपयोगकर्ता नाम |
|
||||
| `--loki-password` | `None` | `LOKI_PASSWORD` | लोकी ऑथ पासवर्ड |
|
||||
264
docs/tech-specs/hi/mcp-tool-arguments.hi.md
Normal file
264
docs/tech-specs/hi/mcp-tool-arguments.hi.md
Normal file
|
|
@ -0,0 +1,264 @@
|
|||
---
|
||||
layout: default
|
||||
title: "एमसीपी टूल आर्गुमेंट्स स्पेसिफिकेशन"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# एमसीपी टूल आर्गुमेंट्स स्पेसिफिकेशन
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
**फ़ीचर नाम**: एमसीपी टूल आर्गुमेंट्स सपोर्ट
|
||||
**लेखक**: क्लाउड कोड असिस्टेंट
|
||||
**तिथि**: 2025-08-21
|
||||
**स्थिति**: अंतिम रूप दिया गया
|
||||
|
||||
### कार्यकारी सारांश
|
||||
|
||||
रीएक्ट एजेंटों को उचित रूप से परिभाषित आर्गुमेंट्स के साथ एमसीपी (मॉडल कॉन्टेक्स्ट प्रोटोकॉल) टूल को उपयोग करने की अनुमति दें,
|
||||
एमसीपी टूल कॉन्फ़िगरेशन में आर्गुमेंट स्पेसिफिकेशन सपोर्ट जोड़कर, उसी तरह जैसे कि प्रॉम्प्ट टेम्पलेट टूल
|
||||
वर्तमान में काम करते हैं।
|
||||
|
||||
### समस्या विवरण
|
||||
|
||||
|
||||
वर्तमान में, रीएक्ट एजेंट फ्रेमवर्क में एमसीपी टूल अपने
|
||||
अपेक्षित आर्गुमेंट्स को निर्दिष्ट नहीं कर सकते हैं। `McpToolImpl.get_arguments()` विधि
|
||||
एक खाली सूची लौटाती है, जिससे एलएलएम को केवल टूल नामों और विवरणों के आधार पर सही पैरामीटर संरचना का अनुमान लगाना पड़ता है।
|
||||
इससे निम्नलिखित समस्याएं होती हैं:
|
||||
पैरामीटर अनुमान के कारण अविश्वसनीय टूल उपयोग
|
||||
गलत आर्गुमेंट्स के कारण टूल विफल होने पर खराब उपयोगकर्ता अनुभव
|
||||
निष्पादन से पहले टूल पैरामीटर का कोई सत्यापन नहीं
|
||||
एजेंट प्रॉम्प्ट में गायब पैरामीटर दस्तावेज़
|
||||
|
||||
### लक्ष्य
|
||||
|
||||
[ ] एमसीपी टूल कॉन्फ़िगरेशन को अपेक्षित आर्गुमेंट्स (नाम, प्रकार, विवरण) निर्दिष्ट करने की अनुमति दें।
|
||||
[ ] एजेंट मैनेजर को एलएलएम को प्रॉम्प्ट के माध्यम से एमसीपी टूल आर्गुमेंट्स को उजागर करने के लिए अपडेट करें।
|
||||
[ ] मौजूदा एमसीपी टूल कॉन्फ़िगरेशन के साथ पिछड़े अनुकूलता बनाए रखें।
|
||||
[ ] प्रॉम्प्ट टेम्पलेट टूल के समान आर्गुमेंट सत्यापन का समर्थन करें।
|
||||
|
||||
### गैर-लक्ष्य
|
||||
एमसीपी सर्वर से गतिशील आर्गुमेंट खोज (भविष्य में सुधार)
|
||||
बुनियादी संरचना से परे आर्गुमेंट प्रकार सत्यापन
|
||||
जटिल आर्गुमेंट स्कीमा (नेस्टेड ऑब्जेक्ट, एरे)
|
||||
|
||||
## पृष्ठभूमि और संदर्भ
|
||||
|
||||
### वर्तमान स्थिति
|
||||
एमसीपी टूल को रीएक्ट एजेंट सिस्टम में न्यूनतम मेटाडेटा के साथ कॉन्फ़िगर किया जाता है:
|
||||
```json
|
||||
{
|
||||
"type": "mcp-tool",
|
||||
"name": "get_bank_balance",
|
||||
"description": "Get bank account balance",
|
||||
"mcp-tool": "get_bank_balance"
|
||||
}
|
||||
```
|
||||
|
||||
`McpToolImpl.get_arguments()` विधि `[]` लौटाती है, इसलिए एलएलएम (LLM) अपने प्रॉम्प्ट में किसी भी तर्क मार्गदर्शन को प्राप्त नहीं करते हैं।
|
||||
|
||||
### सीमाएँ
|
||||
|
||||
1. **कोई तर्क विनिर्देश नहीं**: एमसीपी (MCP) उपकरण अपेक्षित मापदंडों को परिभाषित नहीं कर सकते।
|
||||
पैरामीटर
|
||||
|
||||
2. **एलएलएम पैरामीटर का अनुमान**: एजेंटों को टूल के नामों/वर्णनों से पैरामीटर का अनुमान लगाना होता है।
|
||||
|
||||
3. **गायब प्रॉम्प्ट जानकारी**: एजेंट प्रॉम्प्ट में एमसीपी टूल के लिए किसी भी तर्क विवरण नहीं होते हैं।
|
||||
|
||||
4. **कोई सत्यापन नहीं**: अमान्य पैरामीटर केवल एमसीपी टूल के निष्पादन समय पर ही पकड़े जाते हैं।
|
||||
|
||||
### संबंधित घटक
|
||||
**trustgraph-flow/agent/react/service.py**: टूल कॉन्फ़िगरेशन लोडिंग और एजेंटमैनेजर (AgentManager) निर्माण।
|
||||
**trustgraph-flow/agent/react/tools.py**: McpToolImpl कार्यान्वयन।
|
||||
**trustgraph-flow/agent/react/agent_manager.py**: टूल तर्कों के साथ प्रॉम्प्ट पीढ़ी।
|
||||
**trustgraph-cli**: एमसीपी टूल प्रबंधन के लिए सीएलआई (CLI) उपकरण।
|
||||
**वर्कबेंच (Workbench)**: एजेंट टूल कॉन्फ़िगरेशन के लिए बाहरी यूआई (UI)।
|
||||
|
||||
## आवश्यकताएँ
|
||||
|
||||
### कार्यात्मक आवश्यकताएँ
|
||||
## आवश्यकताएँ
|
||||
|
||||
### कार्यात्मक आवश्यकताएँ
|
||||
|
||||
1. **MCP टूल कॉन्फ़िगरेशन तर्क**: MCP टूल कॉन्फ़िगरेशन में एक वैकल्पिक `arguments` सरणी होनी चाहिए जिसमें नाम, प्रकार और विवरण फ़ील्ड हों।
|
||||
2. **तर्क का प्रदर्शन**: `McpToolImpl.get_arguments()` को खाली सूची के बजाय कॉन्फ़िगर किए गए तर्कों को वापस करना चाहिए।
|
||||
3. **प्रॉम्प्ट एकीकरण**: एजेंट प्रॉम्प्ट में MCP टूल तर्क विवरण शामिल होने चाहिए जब तर्क निर्दिष्ट किए जाते हैं।
|
||||
4. **पिछला अनुकूलता**: बिना तर्कों वाले मौजूदा MCP टूल कॉन्फ़िगरेशन को भी काम करना जारी रखना चाहिए।
|
||||
5. **CLI समर्थन**: मौजूदा `tg-invoke-mcp-tool` CLI तर्कों का समर्थन करता है (पहले से लागू)।
|
||||
|
||||
### गैर-कार्यात्मक आवश्यकताएँ
|
||||
1. **पिछला अनुकूलता**: मौजूदा MCP टूल कॉन्फ़िगरेशन के लिए कोई ब्रेकिंग परिवर्तन नहीं।
|
||||
2. **प्रदर्शन**: एजेंट प्रॉम्प्ट पीढ़ी पर कोई महत्वपूर्ण प्रदर्शन प्रभाव नहीं।
|
||||
3. **संगति**: तर्क हैंडलिंग को प्रॉम्प्ट टेम्पलेट टूल पैटर्न से मेल खाना चाहिए।
|
||||
|
||||
### उपयोगकर्ता कहानियां
|
||||
|
||||
1. एक **एजेंट डेवलपर** के रूप में, मैं LLMs को सही मापदंडों के साथ टूल को आमंत्रित करने के लिए MCP टूल तर्कों को कॉन्फ़िगरेशन में निर्दिष्ट करना चाहता हूं।
|
||||
2. एक **वर्कबेंच उपयोगकर्ता** के रूप में, मैं एजेंटों को सही ढंग से टूल का उपयोग करने के लिए UI में MCP टूल तर्कों को कॉन्फ़िगर करना चाहता हूं।
|
||||
3. एक **ReACT एजेंट में एक LLM** के रूप में, मैं सही मापदंडों प्रदान करने के लिए प्रॉम्प्ट में टूल तर्क विनिर्देशों को देखना चाहता हूं।
|
||||
|
||||
## डिज़ाइन
|
||||
|
||||
### उच्च-स्तरीय आर्किटेक्चर
|
||||
MCP टूल कॉन्फ़िगरेशन को प्रॉम्प्ट टेम्पलेट पैटर्न से मिलाने के लिए:
|
||||
1. MCP टूल कॉन्फ़िगरेशन में एक वैकल्पिक `arguments` सरणी जोड़ें।
|
||||
2. `McpToolImpl` को कॉन्फ़िगर किए गए तर्कों को स्वीकार करने और वापस करने के लिए संशोधित करें।
|
||||
3. MCP टूल तर्कों को संभालने के लिए टूल कॉन्फ़िगरेशन लोडिंग को अपडेट करें।
|
||||
4. सुनिश्चित करें कि एजेंट प्रॉम्प्ट में MCP टूल तर्क जानकारी शामिल है।
|
||||
|
||||
### कॉन्फ़िगरेशन स्कीमा
|
||||
```json
|
||||
{
|
||||
"type": "mcp-tool",
|
||||
"name": "get_bank_balance",
|
||||
"description": "Get bank account balance",
|
||||
"mcp-tool": "get_bank_balance",
|
||||
"arguments": [
|
||||
{
|
||||
"name": "account_id",
|
||||
"type": "string",
|
||||
"description": "Bank account identifier"
|
||||
},
|
||||
{
|
||||
"name": "date",
|
||||
"type": "string",
|
||||
"description": "Date for balance query (optional, format: YYYY-MM-DD)"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### डेटा प्रवाह
|
||||
1. **कॉन्फ़िगरेशन लोडिंग**: एमसीपी टूल कॉन्फ़िगरेशन और तर्क `on_tools_config()` द्वारा लोड किए जाते हैं।
|
||||
2. **टूल निर्माण**: तर्कों को पार्स किया जाता है और `McpToolImpl` को कंस्ट्रक्टर के माध्यम से पास किया जाता है।
|
||||
3. **प्रॉम्प्ट जनरेशन**: `agent_manager.py` एलएलएम प्रॉम्प्ट में शामिल करने के लिए `tool.arguments` को कॉल करता है।
|
||||
4. **टूल इनवोकेशन**: एलएलएम पैरामीटर प्रदान करता है जिन्हें एमसीपी सेवा को बिना किसी बदलाव के पास किया जाता है।
|
||||
|
||||
### एपीआई परिवर्तन
|
||||
कोई बाहरी एपीआई परिवर्तन नहीं - यह पूरी तरह से आंतरिक कॉन्फ़िगरेशन और तर्क प्रबंधन है।
|
||||
|
||||
### घटक विवरण
|
||||
|
||||
#### घटक 1: service.py (टूल कॉन्फ़िगरेशन लोडिंग)
|
||||
**उद्देश्य**: एमसीपी टूल कॉन्फ़िगरेशन को पार्स करें और टूल इंस्टेंस बनाएं।
|
||||
**आवश्यक परिवर्तन**: एमसीपी टूल के लिए तर्क पार्सिंग जोड़ें (प्रॉम्प्ट टूल के समान)।
|
||||
**नई कार्यक्षमता**: एमसीपी टूल कॉन्फ़िगरेशन से `arguments` सरणी निकालें और `Argument` ऑब्जेक्ट बनाएं।
|
||||
|
||||
#### घटक 2: tools.py (McpToolImpl)
|
||||
**उद्देश्य**: एमसीपी टूल कार्यान्वयन रैपर।
|
||||
**आवश्यक परिवर्तन**: कंस्ट्रक्टर में तर्क स्वीकार करें और उन्हें `get_arguments()` से वापस करें।
|
||||
**नई कार्यक्षमता**: कॉन्फ़िगर किए गए तर्कों को संग्रहीत करें और प्रदर्शित करें, खाली सूची वापस करने के बजाय।
|
||||
|
||||
#### घटक 3: वर्कबेंच (बाहरी रिपॉजिटरी)
|
||||
**उद्देश्य**: एजेंट टूल को कॉन्फ़िगर करने के लिए यूआई।
|
||||
**आवश्यक परिवर्तन**: एमसीपी टूल के लिए तर्क विनिर्देश यूआई जोड़ें।
|
||||
**नई कार्यक्षमता**: उपयोगकर्ताओं को एमसीपी टूल के लिए तर्क जोड़ने/संपादित करने/हटाने की अनुमति दें।
|
||||
|
||||
#### घटक 4: सीएलआई टूल
|
||||
**उद्देश्य**: कमांड-लाइन टूल प्रबंधन।
|
||||
**आवश्यक परिवर्तन**: एमसीपी टूल निर्माण/अपडेट कमांड में तर्क विनिर्देश का समर्थन करें।
|
||||
**नई कार्यक्षमता**: टूल कॉन्फ़िगरेशन कमांड में तर्क पैरामीटर स्वीकार करें।
|
||||
|
||||
## कार्यान्वयन योजना
|
||||
|
||||
### चरण 1: कोर एजेंट फ्रेमवर्क परिवर्तन
|
||||
[ ] `McpToolImpl` कंस्ट्रक्टर को `arguments` पैरामीटर स्वीकार करने के लिए अपडेट करें।
|
||||
[ ] `McpToolImpl.get_arguments()` को संग्रहीत तर्कों को वापस करने के लिए बदलें।
|
||||
[ ] तर्कों को संभालने के लिए `service.py` एमसीपी टूल कॉन्फ़िगरेशन पार्सिंग को संशोधित करें।
|
||||
[ ] एमसीपी टूल तर्क हैंडलिंग के लिए यूनिट टेस्ट जोड़ें।
|
||||
[ ] सत्यापित करें कि एजेंट प्रॉम्प्ट में एमसीपी टूल तर्क शामिल हैं।
|
||||
|
||||
### चरण 2: बाहरी टूल समर्थन
|
||||
[ ] एमसीपी टूल तर्क विनिर्देश का समर्थन करने के लिए सीएलआई टूल को अपडेट करें।
|
||||
[ ] उपयोगकर्ताओं के लिए तर्क कॉन्फ़िगरेशन प्रारूप का दस्तावेज़ बनाएं।
|
||||
[ ] एमसीपी टूल तर्क कॉन्फ़िगरेशन का समर्थन करने के लिए वर्कबेंच यूआई को अपडेट करें।
|
||||
[ ] उदाहरण और दस्तावेज़ जोड़ें।
|
||||
|
||||
### कोड परिवर्तन सारांश
|
||||
| फ़ाइल | परिवर्तन का प्रकार | विवरण |
|
||||
|------|------------|-------------|
|
||||
| `tools.py` | संशोधित | `tools.py` को तर्क स्वीकार करने और संग्रहीत करने के लिए अपडेट करें |
|
||||
| `service.py` | संशोधित | एमसीपी टूल कॉन्फ़िगरेशन से तर्कों को पार्स करें (पंक्ति 108-113) |
|
||||
| `test_react_processor.py` | संशोधित | एमसीपी टूल तर्कों के लिए परीक्षण जोड़ें |
|
||||
| सीएलआई टूल | संशोधित | कमांड में तर्क विनिर्देश का समर्थन करें |
|
||||
| वर्कबेंच | संशोधित | एमसीपी टूल तर्क कॉन्फ़िगरेशन के लिए यूआई जोड़ें |
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
### यूनिट टेस्ट
|
||||
**एमसीपी टूल तर्क पार्सिंग**: परीक्षण करें कि `service.py` एमसीपी टूल कॉन्फ़िगरेशन से तर्कों को सही ढंग से पार्स करता है।
|
||||
**McpToolImpl तर्क**: परीक्षण करें कि `get_arguments()` कॉन्फ़िगर किए गए तर्कों को वापस करता है, खाली सूची के बजाय।
|
||||
**पिछला अनुकूलता**: परीक्षण करें कि तर्कों के बिना एमसीपी टूल काम करना जारी रखते हैं (खाली सूची वापस करें)।
|
||||
**एजेंट प्रॉम्प्ट जनरेशन**: परीक्षण करें कि एजेंट प्रॉम्प्ट में एमसीपी टूल तर्क विवरण शामिल हैं।
|
||||
|
||||
### एकीकरण परीक्षण
|
||||
**एंड-टू-एंड टूल इनवोकेशन**: एमसीपी टूल आर्गुमेंट्स के साथ टेस्ट एजेंट सफलतापूर्वक टूल को इनवोक कर सकता है।
|
||||
**कॉन्फ़िगरेशन लोडिंग**: एमसीपी टूल आर्गुमेंट्स के साथ टेस्ट संपूर्ण कॉन्फ़िगरेशन लोडिंग साइकिल।
|
||||
**क्रॉस-कंपोनेंट**: टेस्ट आर्गुमेंट्स का प्रवाह सही ढंग से कॉन्फ़िगरेशन → टूल क्रिएशन → प्रॉम्प्ट जेनरेशन से होता है।
|
||||
|
||||
### मैनुअल टेस्टिंग
|
||||
**एजेंट बिहेवियर**: मैन्युअल रूप से सत्यापित करें कि एलएलएम रीएक्ट साइकिल में आर्गुमेंट जानकारी प्राप्त करता है और उसका उपयोग करता है।
|
||||
**सीएलआई इंटीग्रेशन**: टेस्ट `tg-invoke-mcp-tool` नए आर्गुमेंट-कॉन्फ़िगर किए गए एमसीपी टूल के साथ काम करता है।
|
||||
**वर्कबेंच इंटीग्रेशन**: टेस्ट यूआई एमसीपी टूल आर्गुमेंट कॉन्फ़िगरेशन का समर्थन करता है।
|
||||
|
||||
## माइग्रेशन और रोलआउट
|
||||
|
||||
### माइग्रेशन रणनीति
|
||||
माइग्रेशन की आवश्यकता नहीं है - यह पूरी तरह से अतिरिक्त कार्यक्षमता है:
|
||||
मौजूदा एमसीपी टूल कॉन्फ़िगरेशन जिसमें `arguments` नहीं है, वह बिना किसी बदलाव के काम करना जारी रखता है।
|
||||
`McpToolImpl.get_arguments()` लेगेसी टूल के लिए खाली सूची लौटाता है।
|
||||
नए कॉन्फ़िगरेशन वैकल्पिक रूप से `arguments` सरणी शामिल कर सकते हैं।
|
||||
|
||||
### रोलआउट योजना
|
||||
1. **फेज 1**: डेवलपमेंट/स्टेजिंग में कोर एजेंट फ्रेमवर्क परिवर्तनों को तैनात करें।
|
||||
2. **फेज 2**: सीएलआई टूल अपडेट और दस्तावेज़ तैनात करें।
|
||||
3. **फेज 3**: आर्गुमेंट कॉन्फ़िगरेशन के लिए वर्कबेंच यूआई अपडेट तैनात करें।
|
||||
4. **फेज 4**: मॉनिटरिंग के साथ प्रोडक्शन रोलआउट।
|
||||
|
||||
### रोलबैक योजना
|
||||
कोर परिवर्तन पिछड़े संगत हैं - कार्यक्षमता के लिए रोलबैक की आवश्यकता नहीं है।
|
||||
यदि कोई समस्या उत्पन्न होती है, तो एमसीपी टूल कॉन्फ़िगरेशन लोडिंग लॉजिक को वापस करके आर्गुमेंट पार्सिंग को अक्षम करें।
|
||||
वर्कबेंच और सीएलआई परिवर्तन स्वतंत्र हैं और उन्हें अलग से वापस किया जा सकता है।
|
||||
|
||||
## सुरक्षा संबंधी विचार
|
||||
**कोई नया अटैक सरफेस नहीं**: आर्गुमेंट्स मौजूदा कॉन्फ़िगरेशन स्रोतों से पार्स किए जाते हैं, जिसमें कोई नया इनपुट नहीं है।
|
||||
**पैरामीटर सत्यापन**: आर्गुमेंट्स को एमसीपी टूल स्तर पर अपरिवर्तित एमसीपी टूल में पास किया जाता है - सत्यापन एमसीपी टूल स्तर पर रहता है।
|
||||
**कॉन्फ़िगरेशन अखंडता**: आर्गुमेंट विनिर्देश टूल कॉन्फ़िगरेशन का हिस्सा हैं - समान सुरक्षा मॉडल लागू होता है।
|
||||
|
||||
## प्रदर्शन प्रभाव
|
||||
**न्यूनतम ओवरहेड**: आर्गुमेंट पार्सिंग केवल कॉन्फ़िगरेशन लोडिंग के दौरान होती है, प्रति-अनुरोध नहीं।
|
||||
**प्रॉम्प्ट आकार में वृद्धि**: एजेंट प्रॉम्प्ट में एमसीपी टूल आर्गुमेंट विवरण शामिल होंगे, जिससे टोकन उपयोग थोड़ा बढ़ जाएगा।
|
||||
**मेमोरी उपयोग**: टूल ऑब्जेक्ट में आर्गुमेंट विनिर्देशों को संग्रहीत करने के लिए मामूली वृद्धि।
|
||||
|
||||
## दस्तावेज़
|
||||
|
||||
### उपयोगकर्ता दस्तावेज़
|
||||
[ ] आर्गुमेंट उदाहरणों के साथ एमसीपी टूल कॉन्फ़िगरेशन गाइड को अपडेट करें।
|
||||
[ ] सीएलआई टूल हेल्प टेक्स्ट में आर्गुमेंट विनिर्देश जोड़ें।
|
||||
[ ] सामान्य एमसीपी टूल आर्गुमेंट पैटर्न के उदाहरण बनाएं।
|
||||
|
||||
### डेवलपर दस्तावेज़
|
||||
[ ] `McpToolImpl` क्लास दस्तावेज़ को अपडेट करें।
|
||||
[ ] आर्गुमेंट पार्सिंग लॉजिक के लिए इनलाइन टिप्पणियाँ जोड़ें।
|
||||
[ ] सिस्टम आर्किटेक्चर में आर्गुमेंट प्रवाह का दस्तावेज़ बनाएं।
|
||||
|
||||
## खुले प्रश्न
|
||||
1. **आर्गुमेंट सत्यापन**: क्या हमें बुनियादी संरचना जांच से परे आर्गुमेंट प्रकार/प्रारूपों को मान्य करना चाहिए?
|
||||
2. **डायनामिक डिस्कवरी**: एमसीपी सर्वर से टूल स्कीमा को स्वचालित रूप से क्वेरी करने के लिए भविष्य में संवर्द्धन?
|
||||
|
||||
## विचारे गए विकल्प
|
||||
1. **डायनामिक एमसीपी स्कीमा डिस्कवरी**: रनटाइम पर टूल आर्गुमेंट स्कीमा के लिए एमसीपी सर्वर को क्वेरी करें - जटिलता और विश्वसनीयता संबंधी चिंताओं के कारण अस्वीकृत।
|
||||
2. **अलग आर्गुमेंट रजिस्ट्री**: एमसीपी टूल आर्गुमेंट को अलग कॉन्फ़िगरेशन अनुभाग में संग्रहीत करें - प्रॉम्प्ट टेम्पलेट दृष्टिकोण के साथ स्थिरता के कारण अस्वीकृत।
|
||||
3. **टाइप सत्यापन**: आर्गुमेंट के लिए पूर्ण JSON स्कीमा सत्यापन - प्रारंभिक कार्यान्वयन को सरल रखने के लिए भविष्य के संवर्द्धन के रूप में स्थगित।
|
||||
|
||||
## संदर्भ
|
||||
[एमसीपी प्रोटोकॉल विनिर्देश](https://github.com/modelcontextprotocol/spec)
|
||||
[प्रॉम्प्ट टेम्पलेट टूल कार्यान्वयन](./trustgraph-flow/trustgraph/agent/react/service.py#L114-129)
|
||||
[वर्तमान एमसीपी टूल कार्यान्वयन](./trustgraph-flow/trustgraph/agent/react/tools.py#L58-86)
|
||||
|
||||
## परिशिष्ट
|
||||
[कोई भी अतिरिक्त जानकारी, आरेख या उदाहरण]
|
||||
562
docs/tech-specs/hi/mcp-tool-bearer-token.hi.md
Normal file
562
docs/tech-specs/hi/mcp-tool-bearer-token.hi.md
Normal file
|
|
@ -0,0 +1,562 @@
|
|||
---
|
||||
layout: default
|
||||
title: "एमसीपी टूल बेयरर टोकन प्रमाणीकरण विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# एमसीपी टूल बेयरर टोकन प्रमाणीकरण विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
> **⚠️ महत्वपूर्ण: केवल सिंगल-टेनेन्ट**
|
||||
>
|
||||
> यह विनिर्देश एमसीपी टूल के लिए एक **बुनियादी, सेवा-स्तर प्रमाणीकरण तंत्र** का वर्णन करता है। यह एक पूर्ण प्रमाणीकरण समाधान **नहीं** है और यह निम्नलिखित के लिए **उपयुक्त नहीं** है:
|
||||
> - मल्टी-यूजर वातावरण
|
||||
> - मल्टी-टेनेन्ट परिनियोजन
|
||||
> - फेडरेटेड प्रमाणीकरण
|
||||
> - यूजर संदर्भ का प्रसार
|
||||
> - प्रति-उपयोगकर्ता प्राधिकरण
|
||||
>
|
||||
> यह सुविधा प्रत्येक एमसीपी टूल के लिए **एक स्थिर टोकन** प्रदान करती है, जो सभी उपयोगकर्ताओं और सत्रों में साझा किया जाता है। यदि आपको प्रति-उपयोगकर्ता या प्रति-टेनेन्ट प्रमाणीकरण की आवश्यकता है, तो यह सही समाधान नहीं है।
|
||||
|
||||
## अवलोकन
|
||||
**सुविधा का नाम**: एमसीपी टूल बेयरर टोकन प्रमाणीकरण समर्थन
|
||||
**लेखक**: क्लाउड कोड असिस्टेंट
|
||||
**तिथि**: 2025-11-11
|
||||
**स्थिति**: विकास के अधीन
|
||||
|
||||
### कार्यकारी सारांश
|
||||
|
||||
एमसीपी टूल कॉन्फ़िगरेशन को सुरक्षित एमसीपी सर्वरों के साथ प्रमाणीकरण के लिए वैकल्पिक बेयरर टोकन निर्दिष्ट करने की अनुमति दें। यह ट्रस्टग्राफ को उन सर्वरों पर होस्ट किए गए एमसीपी टूल को सुरक्षित रूप से आमंत्रित करने की अनुमति देता है जिनके लिए प्रमाणीकरण की आवश्यकता होती है, एजेंट या टूल इनवोकेशन इंटरफेस को संशोधित किए बिना।
|
||||
|
||||
**महत्वपूर्ण**: यह एक बुनियादी प्रमाणीकरण तंत्र है जिसे सिंगल-टेनेन्ट, सेवा-से-सेवा प्रमाणीकरण परिदृश्यों के लिए डिज़ाइन किया गया है। यह निम्नलिखित के लिए **उपयुक्त नहीं** है:
|
||||
मल्टी-यूजर वातावरण जहां विभिन्न उपयोगकर्ताओं को अलग-अलग क्रेडेंशियल की आवश्यकता होती है
|
||||
मल्टी-टेनेन्ट परिनियोजन जिसके लिए प्रति-टेनेन्ट अलगाव की आवश्यकता होती है
|
||||
फेडरेटेड प्रमाणीकरण परिदृश्य
|
||||
यूजर-स्तरीय प्रमाणीकरण या प्राधिकरण
|
||||
गतिशील क्रेडेंशियल प्रबंधन या टोकन रीफ़्रेश
|
||||
|
||||
यह सुविधा प्रत्येक एमसीपी टूल कॉन्फ़िगरेशन के लिए एक स्थिर, सिस्टम-व्यापी बेयरर टोकन प्रदान करती है, जो उस टूल के सभी उपयोगकर्ताओं और इनवोकेशन में साझा किया जाता है।
|
||||
|
||||
### समस्या विवरण
|
||||
|
||||
वर्तमान में, एमसीपी टूल केवल सार्वजनिक रूप से सुलभ एमसीपी सर्वरों से जुड़ सकते हैं। कई उत्पादन एमसीपी परिनियोजन सुरक्षा के लिए बेयरर टोकन के माध्यम से प्रमाणीकरण की आवश्यकता होती है। प्रमाणीकरण समर्थन के बिना:
|
||||
एमसीपी टूल सुरक्षित एमसीपी सर्वरों से कनेक्ट नहीं हो सकते
|
||||
उपयोगकर्ताओं को या तो एमसीपी सर्वरों को सार्वजनिक रूप से उजागर करना होगा या रिवर्स प्रॉक्सी लागू करना होगा
|
||||
एमसीपी कनेक्शनों को क्रेडेंशियल पास करने का कोई मानकीकृत तरीका नहीं है
|
||||
एमसीपी एंडपॉइंट पर सुरक्षा सर्वोत्तम प्रथाओं को लागू नहीं किया जा सकता है
|
||||
|
||||
### लक्ष्य
|
||||
|
||||
[ ] एमसीपी टूल कॉन्फ़िगरेशन को वैकल्पिक `auth-token` पैरामीटर निर्दिष्ट करने की अनुमति दें
|
||||
[ ] एमसीपी टूल सेवा को एमसीपी सर्वरों से कनेक्ट करते समय बेयरर टोकन का उपयोग करने के लिए अपडेट करें
|
||||
[ ] CLI टूल को ऑथ टोकन सेट/डिस्प्ले करने के लिए अपडेट करें
|
||||
[ ] अप्रामाणित एमसीपी कॉन्फ़िगरेशन के साथ बैकवर्ड संगतता बनाए रखें
|
||||
[ ] टोकन स्टोरेज के लिए सुरक्षा विचारों का दस्तावेजीकरण करें
|
||||
|
||||
### गैर-लक्ष्य
|
||||
गतिशील टोकन रीफ़्रेश या OAuth प्रवाह (केवल स्थिर टोकन)
|
||||
संग्रहीत टोकन का एन्क्रिप्शन (कॉन्फ़िगरेशन सिस्टम सुरक्षा दायरे से बाहर है)
|
||||
वैकल्पिक प्रमाणीकरण विधियाँ (बेसिक ऑथ, एपीआई कुंजियाँ, आदि)
|
||||
टोकन सत्यापन या समाप्ति जांच
|
||||
**प्रति-उपयोगकर्ता प्रमाणीकरण**: यह सुविधा उपयोगकर्ता-विशिष्ट क्रेडेंशियल का समर्थन नहीं करती है
|
||||
**मल्टी-टेनेन्ट अलगाव**: यह सुविधा प्रति-टेनेन्ट टोकन प्रबंधन प्रदान नहीं करती है
|
||||
**फेडरेटेड प्रमाणीकरण**: यह सुविधा पहचान प्रदाताओं (एसएसओ, OAuth, SAML, आदि) के साथ एकीकृत नहीं होती है
|
||||
**संदर्भ-जागरूक प्रमाणीकरण**: टोकन उपयोगकर्ता संदर्भ या सत्र के आधार पर पास नहीं किए जाते हैं
|
||||
|
||||
## पृष्ठभूमि और संदर्भ
|
||||
|
||||
### वर्तमान स्थिति
|
||||
एमसीपी टूल कॉन्फ़िगरेशन `mcp` कॉन्फ़िगरेशन समूह में इस संरचना के साथ संग्रहीत हैं:
|
||||
```json
|
||||
{
|
||||
"remote-name": "tool_name",
|
||||
"url": "http://mcp-server:3000/api"
|
||||
}
|
||||
```
|
||||
|
||||
MCP टूल सेवा `streamablehttp_client(url)` का उपयोग करके सर्वरों से कनेक्ट होती है, बिना किसी प्रमाणीकरण हेडर के।
|
||||
|
||||
### सीमाएँ
|
||||
|
||||
**वर्तमान सिस्टम सीमाएँ:**
|
||||
1. **कोई प्रमाणीकरण समर्थन नहीं:** सुरक्षित MCP सर्वरों से कनेक्ट नहीं किया जा सकता।
|
||||
2. **सुरक्षा जोखिम:** MCP सर्वर सार्वजनिक रूप से सुलभ होने चाहिए या केवल नेटवर्क-स्तरीय सुरक्षा का उपयोग करना चाहिए।
|
||||
3. **उत्पादन परिनियोजन मुद्दे:** API एंडपॉइंट्स के लिए सुरक्षा सर्वोत्तम प्रथाओं का पालन नहीं किया जा सकता।
|
||||
|
||||
**इस समाधान की सीमाएँ:**
|
||||
1. **केवल सिंगल-टेनेन्ट:** प्रत्येक MCP टूल के लिए एक स्थिर टोकन, सभी उपयोगकर्ताओं में साझा।
|
||||
2. **प्रति-उपयोगकर्ता क्रेडेंशियल्स नहीं:** विभिन्न उपयोगकर्ताओं के रूप में प्रमाणीकरण नहीं किया जा सकता या उपयोगकर्ता संदर्भ नहीं भेजा जा सकता।
|
||||
3. **कोई मल्टी-टेनेन्ट समर्थन नहीं:** क्रेडेंशियल्स को टेनेन्ट या संगठन द्वारा अलग नहीं किया जा सकता।
|
||||
4. **केवल स्थिर टोकन:** टोकन रीफ़्रेश, रोटेशन या समाप्ति प्रबंधन का कोई समर्थन नहीं।
|
||||
5. **सेवा-स्तरीय प्रमाणीकरण:** ट्रस्टग्राफ सेवा को प्रमाणित करता है, व्यक्तिगत उपयोगकर्ताओं को नहीं।
|
||||
6. **साझा सुरक्षा संदर्भ:** MCP टूल के सभी आह्वान एक ही क्रेडेंशियल का उपयोग करते हैं।
|
||||
|
||||
### उपयोग मामला प्रयोज्यता
|
||||
|
||||
**✅ उपयुक्त उपयोग मामले:**
|
||||
सिंगल-टेनेन्ट ट्रस्टग्राफ परिनियोजन।
|
||||
सेवा-से-सेवा प्रमाणीकरण (ट्रस्टग्राफ → MCP सर्वर)।
|
||||
विकास और परीक्षण वातावरण।
|
||||
ट्रस्टग्राफ सिस्टम द्वारा एक्सेस किए जाने वाले आंतरिक MCP टूल।
|
||||
ऐसे परिदृश्य जहां सभी उपयोगकर्ताओं के पास MCP टूल तक समान पहुंच स्तर हो।
|
||||
स्थिर, लंबे समय तक चलने वाले सेवा क्रेडेंशियल्स।
|
||||
|
||||
**❌ अनुपयुक्त उपयोग मामले:**
|
||||
प्रति-उपयोगकर्ता प्रमाणीकरण की आवश्यकता वाले मल्टी-यूजर सिस्टम।
|
||||
टेनेन्ट अलगाव आवश्यकताओं वाले मल्टी-टेनेन्ट SaaS परिनियोजन।
|
||||
फेडरेटेड प्रमाणीकरण परिदृश्य (SSO, OAuth, SAML)।
|
||||
ऐसे सिस्टम जिनके लिए MCP सर्वरों पर उपयोगकर्ता संदर्भ का प्रसार आवश्यक है।
|
||||
ऐसे वातावरण जिन्हें गतिशील टोकन रीफ़्रेश या अल्पकालिक टोकन की आवश्यकता होती है।
|
||||
ऐसे एप्लिकेशन जहां विभिन्न उपयोगकर्ताओं को अलग-अलग अनुमति स्तरों की आवश्यकता होती है।
|
||||
उपयोगकर्ता-स्तरीय ऑडिट ट्रेल्स के लिए अनुपालन आवश्यकताएं।
|
||||
|
||||
**उदाहरण उपयुक्त परिदृश्य:**
|
||||
एक सिंगल-संगठन ट्रस्टग्राफ परिनियोजन जहां सभी कर्मचारी एक ही आंतरिक MCP टूल का उपयोग करते हैं (उदाहरण के लिए, कंपनी डेटाबेस लुकअप)। MCP सर्वर को बाहरी पहुंच को रोकने के लिए प्रमाणीकरण की आवश्यकता होती है, लेकिन सभी आंतरिक उपयोगकर्ताओं के पास समान पहुंच स्तर होता है।
|
||||
|
||||
**उदाहरण अनुपयुक्त परिदृश्य:**
|
||||
एक मल्टी-टेनेन्ट ट्रस्टग्राफ SaaS प्लेटफ़ॉर्म जहां टेनेन्ट A और टेनेन्ट B को अलग-अलग क्रेडेंशियल्स के साथ अपने स्वयं के अलग-अलग MCP सर्वरों तक पहुंचने की आवश्यकता होती है। यह सुविधा प्रति-टेनेन्ट टोकन प्रबंधन का समर्थन नहीं करती है।
|
||||
|
||||
### संबंधित घटक
|
||||
**trustgraph-flow/trustgraph/agent/mcp_tool/service.py**: MCP टूल इनवोकेशन सेवा।
|
||||
**trustgraph-cli/trustgraph/cli/set_mcp_tool.py**: MCP कॉन्फ़िगरेशन बनाने/अपडेट करने के लिए CLI टूल।
|
||||
**trustgraph-cli/trustgraph/cli/show_mcp_tools.py**: MCP कॉन्फ़िगरेशन प्रदर्शित करने के लिए CLI टूल।
|
||||
**MCP Python SDK**: `streamablehttp_client` from `mcp.client.streamable_http`
|
||||
|
||||
## आवश्यकताएँ
|
||||
|
||||
### कार्यात्मक आवश्यकताएँ
|
||||
|
||||
1. **MCP कॉन्फ़िगरेशन ऑथ टोकन:** MCP टूल कॉन्फ़िगरेशन को एक वैकल्पिक `auth-token` फ़ील्ड का समर्थन करना चाहिए।
|
||||
2. **बियरर टोकन उपयोग:** MCP टूल सेवा को `Authorization: Bearer {token}` हेडर भेजना चाहिए जब ऑथ-टोकन कॉन्फ़िगर किया गया हो।
|
||||
3. **CLI समर्थन:** `tg-set-mcp-tool` को एक वैकल्पिक `--auth-token` पैरामीटर स्वीकार करना चाहिए।
|
||||
4. **टोकन प्रदर्शन:** `tg-show-mcp-tools` को यह इंगित करना चाहिए कि ऑथ-टोकन कॉन्फ़िगर किया गया है (सुरक्षा के लिए मास्क किया गया)।
|
||||
5. **पिछला अनुकूलता:** ऑथ-टोकन के बिना मौजूदा MCP टूल कॉन्फ़िगरेशन को काम करना जारी रखना चाहिए।
|
||||
|
||||
### गैर-कार्यात्मक आवश्यकताएँ
|
||||
1. **पिछला अनुकूलता:** मौजूदा MCP टूल कॉन्फ़िगरेशन के लिए कोई ब्रेकिंग परिवर्तन नहीं।
|
||||
2. **प्रदर्शन:** MCP टूल इनवोकेशन पर कोई महत्वपूर्ण प्रदर्शन प्रभाव नहीं।
|
||||
3. **सुरक्षा:** कॉन्फ़िगरेशन में संग्रहीत टोकन (सुरक्षा निहितार्थों का दस्तावेजीकरण करें)।
|
||||
|
||||
### उपयोगकर्ता कहानियाँ
|
||||
|
||||
1. एक **DevOps इंजीनियर** के रूप में, मैं MCP टूल के लिए बियरर टोकन कॉन्फ़िगर करना चाहता हूं ताकि मैं MCP सर्वर एंडपॉइंट्स को सुरक्षित कर सकूं।
|
||||
2. एक **CLI उपयोगकर्ता** के रूप में, मैं MCP टूल बनाते समय ऑथ टोकन सेट करना चाहता हूं ताकि मैं संरक्षित सर्वरों से कनेक्ट कर सकूं।
|
||||
3. एक **सिस्टम प्रशासक** के रूप में, मैं यह देखना चाहता हूं कि किन MCP टूल में प्रमाणीकरण कॉन्फ़िगर किया गया है ताकि मैं सुरक्षा सेटिंग्स का ऑडिट कर सकूं।
|
||||
|
||||
## डिज़ाइन
|
||||
|
||||
### उच्च-स्तरीय आर्किटेक्चर
|
||||
MCP टूल कॉन्फ़िगरेशन और सेवा को बियरर टोकन प्रमाणीकरण का समर्थन करने के लिए विस्तारित करें:
|
||||
1. MCP टूल कॉन्फ़िगरेशन स्कीमा में एक वैकल्पिक `auth-token` फ़ील्ड जोड़ें।
|
||||
2. MCP टूल सेवा को ऑथ-टोकन पढ़ने और इसे HTTP क्लाइंट को पास करने के लिए संशोधित करें।
|
||||
3. ऑथ टोकन सेट करने और प्रदर्शित करने के लिए CLI टूल को अपडेट करें।
|
||||
4. सुरक्षा विचारों और सर्वोत्तम प्रथाओं का दस्तावेजीकरण करें।
|
||||
|
||||
### कॉन्फ़िगरेशन स्कीमा
|
||||
|
||||
**वर्तमान स्कीमा:**
|
||||
```json
|
||||
{
|
||||
"remote-name": "tool_name",
|
||||
"url": "http://mcp-server:3000/api"
|
||||
}
|
||||
```
|
||||
|
||||
**नया स्कीमा** (वैकल्पिक ऑथ-टोकन के साथ):
|
||||
```json
|
||||
{
|
||||
"remote-name": "tool_name",
|
||||
"url": "http://mcp-server:3000/api",
|
||||
"auth-token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
}
|
||||
```
|
||||
|
||||
**फ़ील्ड विवरण:**
|
||||
`remote-name` (वैकल्पिक): एमसीपी सर्वर द्वारा उपयोग किया जाने वाला नाम (डिफ़ॉल्ट रूप से कॉन्फ़िगरेशन कुंजी)
|
||||
`url` (आवश्यक): एमसीपी सर्वर एंडपॉइंट यूआरएल
|
||||
`auth-token` (वैकल्पिक): प्रमाणीकरण के लिए बेयरर टोकन
|
||||
|
||||
### डेटा प्रवाह
|
||||
|
||||
1. **कॉन्फ़िगरेशन संग्रहण:** उपयोगकर्ता `tg-set-mcp-tool --id my-tool --tool-url http://server/api --auth-token xyz123` चलाता है
|
||||
2. **कॉन्फ़िगरेशन लोडिंग:** एमसीपी टूल सेवा `on_mcp_config()` कॉलबैक के माध्यम से कॉन्फ़िगरेशन अपडेट प्राप्त करती है
|
||||
3. **टूल इनवोकेशन:** जब टूल को बुलाया जाता है:
|
||||
सेवा कॉन्फ़िगरेशन से `auth-token` पढ़ती है (यदि मौजूद है)
|
||||
हेडर डिक्ट बनाता है: `{"Authorization": "Bearer {token}"}`
|
||||
हेडर को `streamablehttp_client(url, headers=headers)` में पास करता है
|
||||
एमसीपी सर्वर टोकन को मान्य करता है और अनुरोध को संसाधित करता है
|
||||
|
||||
### एपीआई परिवर्तन
|
||||
कोई बाहरी एपीआई परिवर्तन नहीं - केवल कॉन्फ़िगरेशन स्कीमा एक्सटेंशन।
|
||||
|
||||
### घटक विवरण
|
||||
|
||||
#### घटक 1: service.py (एमसीपी टूल सेवा)
|
||||
**फ़ाइल:** `trustgraph-flow/trustgraph/agent/mcp_tool/service.py`
|
||||
|
||||
**उद्देश्य:** दूरस्थ सर्वरों पर एमसीपी टूल को इनवोक करना
|
||||
|
||||
**आवश्यक परिवर्तन** (`invoke_tool()` विधि में):
|
||||
1. `self.mcp_services[name]` कॉन्फ़िगरेशन में `auth-token` की जाँच करें
|
||||
2. यदि टोकन मौजूद है तो ऑथराइजेशन हेडर के साथ हेडर डिक्ट बनाएं
|
||||
3. हेडर को `streamablehttp_client(url, headers=headers)` में पास करें
|
||||
|
||||
**वर्तमान कोड** (पंक्तियाँ 42-89):
|
||||
```python
|
||||
async def invoke_tool(self, name, parameters):
|
||||
try:
|
||||
if name not in self.mcp_services:
|
||||
raise RuntimeError(f"MCP service {name} not known")
|
||||
if "url" not in self.mcp_services[name]:
|
||||
raise RuntimeError(f"MCP service {name} URL not defined")
|
||||
|
||||
url = self.mcp_services[name]["url"]
|
||||
|
||||
if "remote-name" in self.mcp_services[name]:
|
||||
remote_name = self.mcp_services[name]["remote-name"]
|
||||
else:
|
||||
remote_name = name
|
||||
|
||||
logger.info(f"Invoking {remote_name} at {url}")
|
||||
|
||||
# Connect to a streamable HTTP server
|
||||
async with streamablehttp_client(url) as (
|
||||
read_stream,
|
||||
write_stream,
|
||||
_,
|
||||
):
|
||||
# ... rest of method
|
||||
```
|
||||
|
||||
**संशोधित कोड:**
|
||||
```python
|
||||
async def invoke_tool(self, name, parameters):
|
||||
try:
|
||||
if name not in self.mcp_services:
|
||||
raise RuntimeError(f"MCP service {name} not known")
|
||||
if "url" not in self.mcp_services[name]:
|
||||
raise RuntimeError(f"MCP service {name} URL not defined")
|
||||
|
||||
url = self.mcp_services[name]["url"]
|
||||
|
||||
if "remote-name" in self.mcp_services[name]:
|
||||
remote_name = self.mcp_services[name]["remote-name"]
|
||||
else:
|
||||
remote_name = name
|
||||
|
||||
# Build headers with optional bearer token
|
||||
headers = {}
|
||||
if "auth-token" in self.mcp_services[name]:
|
||||
token = self.mcp_services[name]["auth-token"]
|
||||
headers["Authorization"] = f"Bearer {token}"
|
||||
|
||||
logger.info(f"Invoking {remote_name} at {url}")
|
||||
|
||||
# Connect to a streamable HTTP server with headers
|
||||
async with streamablehttp_client(url, headers=headers) as (
|
||||
read_stream,
|
||||
write_stream,
|
||||
_,
|
||||
):
|
||||
# ... rest of method (unchanged)
|
||||
```
|
||||
|
||||
#### घटक 2: set_mcp_tool.py (सीएलआई कॉन्फ़िगरेशन टूल)
|
||||
**फ़ाइल**: `trustgraph-cli/trustgraph/cli/set_mcp_tool.py`
|
||||
|
||||
**उद्देश्य**: एमसीपी टूल कॉन्फ़िगरेशन बनाना/अपडेट करना
|
||||
|
||||
**आवश्यक परिवर्तन**:
|
||||
1. आर्गुमेंटपार्सर में `--auth-token` वैकल्पिक तर्क जोड़ें
|
||||
2. प्रदान किए जाने पर कॉन्फ़िगरेशन JSON में `auth-token` शामिल करें
|
||||
|
||||
**वर्तमान तर्क**:
|
||||
`--id` (आवश्यक): एमसीपी टूल पहचानकर्ता
|
||||
`--remote-name` (वैकल्पिक): रिमोट एमसीपी टूल नाम
|
||||
`--tool-url` (आवश्यक): एमसीपी टूल यूआरएल एंडपॉइंट
|
||||
`-u, --api-url` (वैकल्पिक): ट्रस्टग्राफ एपीआई यूआरएल
|
||||
|
||||
**नया तर्क**:
|
||||
`--auth-token` (वैकल्पिक): प्रमाणीकरण के लिए बेयरर टोकन
|
||||
|
||||
**संशोधित कॉन्फ़िगरेशन निर्माण**:
|
||||
```python
|
||||
# Build configuration object
|
||||
config = {
|
||||
"url": args.tool_url,
|
||||
}
|
||||
|
||||
if args.remote_name:
|
||||
config["remote-name"] = args.remote_name
|
||||
|
||||
if args.auth_token:
|
||||
config["auth-token"] = args.auth_token
|
||||
|
||||
# Store configuration
|
||||
api.config().put([
|
||||
ConfigValue(type="mcp", key=args.id, value=json.dumps(config))
|
||||
])
|
||||
```
|
||||
|
||||
#### घटक 3: show_mcp_tools.py (सीएलआई डिस्प्ले टूल)
|
||||
**फ़ाइल**: `trustgraph-cli/trustgraph/cli/show_mcp_tools.py`
|
||||
|
||||
**उद्देश्य**: एमसीपी टूल कॉन्फ़िगरेशन प्रदर्शित करना
|
||||
|
||||
**आवश्यक परिवर्तन**:
|
||||
1. आउटपुट तालिका में "Auth" कॉलम जोड़ें
|
||||
2. "हाँ" या "नहीं" प्रदर्शित करें, यह इस आधार पर कि क्या auth-token मौजूद है
|
||||
3. वास्तविक टोकन मान प्रदर्शित न करें (सुरक्षा)
|
||||
|
||||
**वर्तमान आउटपुट**:
|
||||
```
|
||||
ID Remote Name URL
|
||||
---------- ------------- ------------------------
|
||||
my-tool my-tool http://server:3000/api
|
||||
```
|
||||
|
||||
**नया आउटपुट**:
|
||||
```
|
||||
ID Remote Name URL Auth
|
||||
---------- ------------- ------------------------ ------
|
||||
my-tool my-tool http://server:3000/api Yes
|
||||
other-tool other-tool http://other:3000/api No
|
||||
```
|
||||
|
||||
#### घटक 4: दस्तावेज़
|
||||
**फ़ाइल**: `docs/cli/tg-set-mcp-tool.md`
|
||||
|
||||
**आवश्यक परिवर्तन**:
|
||||
1. नए `--auth-token` पैरामीटर का दस्तावेज़ बनाएं
|
||||
2. प्रमाणीकरण के साथ उपयोग का उदाहरण प्रदान करें
|
||||
3. सुरक्षा संबंधी विचारों का दस्तावेज़ बनाएं
|
||||
|
||||
## कार्यान्वयन योजना
|
||||
|
||||
### चरण 1: तकनीकी विनिर्देश बनाएं
|
||||
[x] सभी परिवर्तनों का दस्तावेज़ बनाने वाला व्यापक तकनीकी विनिर्देश लिखें
|
||||
|
||||
### चरण 2: MCP टूल सर्विस को अपडेट करें
|
||||
[ ] `service.py` में `invoke_tool()` को संशोधित करें ताकि कॉन्फ़िगरेशन से auth-token पढ़ा जा सके
|
||||
[ ] हेडर डिक्ट बनाएं और इसे `streamablehttp_client` में पास करें
|
||||
[ ] प्रमाणित MCP सर्वर के साथ परीक्षण करें
|
||||
|
||||
### चरण 3: CLI टूल को अपडेट करें
|
||||
[ ] `set_mcp_tool.py` में `--auth-token` तर्क जोड़ें
|
||||
[ ] कॉन्फ़िगरेशन JSON में auth-token शामिल करें
|
||||
[ ] `show_mcp_tools.py` आउटपुट में "Auth" कॉलम जोड़ें
|
||||
[ ] CLI टूल परिवर्तनों का परीक्षण करें
|
||||
|
||||
### चरण 4: दस्तावेज़ को अपडेट करें
|
||||
[ ] `tg-set-mcp-tool.md` में `--auth-token` पैरामीटर का दस्तावेज़ बनाएं
|
||||
[ ] सुरक्षा संबंधी विचारों का अनुभाग जोड़ें
|
||||
[ ] उपयोग का उदाहरण प्रदान करें
|
||||
|
||||
### चरण 5: परीक्षण
|
||||
[ ] MCP टूल auth-token के साथ सफलतापूर्वक कनेक्ट होता है
|
||||
[ ] पिछड़े अनुकूलता का परीक्षण (auth-token के बिना टूल अभी भी काम करते हैं)
|
||||
[ ] CLI टूल auth-token को स्वीकार और संग्रहीत करते हैं, इसका परीक्षण करें
|
||||
[ ] "शो" कमांड auth स्थिति को सही ढंग से प्रदर्शित करता है, इसका परीक्षण करें
|
||||
|
||||
### कोड परिवर्तनों का सारांश
|
||||
| फ़ाइल | परिवर्तन का प्रकार | पंक्तियाँ | विवरण |
|
||||
|------|------------|-------|-------------|
|
||||
| `service.py` | संशोधित | ~52-66 | auth-token पढ़ने और हेडर बनाने के लिए जोड़ा गया |
|
||||
| `set_mcp_tool.py` | संशोधित | ~30-60 | --auth-token तर्क और कॉन्फ़िगरेशन स्टोरेज जोड़ने के लिए |
|
||||
| `show_mcp_tools.py` | संशोधित | ~40-70 | प्रदर्शन के लिए Auth कॉलम जोड़ने के लिए |
|
||||
| `tg-set-mcp-tool.md` | संशोधित | विभिन्न | नए पैरामीटर का दस्तावेज़ बनाने के लिए |
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
### यूनिट परीक्षण
|
||||
**ऑथ टोकन रीडिंग**: परीक्षण करें कि `invoke_tool()` कॉन्फ़िगरेशन से auth-token को सही ढंग से पढ़ता है या नहीं
|
||||
**हेडर बिल्डिंग**: परीक्षण करें कि प्राधिकरण हेडर सही ढंग से Bearer उपसर्ग के साथ बनाया गया है या नहीं
|
||||
**पिछड़ी अनुकूलता**: परीक्षण करें कि auth-token के बिना टूल अपरिवर्तित रूप से काम करते हैं या नहीं
|
||||
**CLI तर्क पार्सिंग**: परीक्षण करें कि `--auth-token` तर्क को सही ढंग से पार्स किया गया है या नहीं
|
||||
|
||||
### एकीकरण परीक्षण
|
||||
**प्रमाणित कनेक्शन**: परीक्षण करें कि MCP टूल सर्विस प्रमाणित सर्वर से कनेक्ट होती है या नहीं
|
||||
**एंड-टू-एंड**: CLI → कॉन्फ़िगरेशन स्टोरेज → auth टोकन के साथ सेवा इनवोकेशन का परीक्षण करें
|
||||
**टोकन की आवश्यकता नहीं है**: परीक्षण करें कि अनधिकृत सर्वर से कनेक्शन अभी भी काम करता है या नहीं
|
||||
|
||||
### मैनुअल परीक्षण
|
||||
**वास्तविक MCP सर्वर**: वास्तविक MCP सर्वर के साथ परीक्षण करें जिसके लिए Bearer टोकन प्रमाणीकरण की आवश्यकता होती है
|
||||
**CLI वर्कफ़्लो**: परीक्षण करें कि टूल को auth के साथ सेट करें → टूल को इनवोक करें → सफलता की पुष्टि करें
|
||||
**डिस्प्ले मास्किंग**: सत्यापित करें कि auth स्थिति दिखाई जाती है लेकिन टोकन मान प्रदर्शित नहीं होता है
|
||||
|
||||
## माइग्रेशन और रोलआउट
|
||||
|
||||
### माइग्रेशन रणनीति
|
||||
माइग्रेशन की आवश्यकता नहीं है - यह विशुद्ध रूप से एक अतिरिक्त कार्यक्षमता है:
|
||||
`auth-token` के बिना मौजूदा MCP टूल कॉन्फ़िगरेशन अपरिवर्तित रूप से काम करना जारी रखते हैं
|
||||
नए कॉन्फ़िगरेशन वैकल्पिक रूप से `auth-token` फ़ील्ड शामिल कर सकते हैं
|
||||
CLI टूल `--auth-token` पैरामीटर को स्वीकार करते हैं लेकिन इसकी आवश्यकता नहीं होती है
|
||||
|
||||
### रोलआउट योजना
|
||||
1. **चरण 1**: विकास/स्टेजिंग पर मुख्य सेवा परिवर्तनों को तैनात करें
|
||||
2. **चरण 2**: CLI टूल अपडेट तैनात करें
|
||||
3. **चरण 3**: दस्तावेज़ को अपडेट करें
|
||||
4. **चरण 4**: निगरानी के साथ उत्पादन रोलआउट
|
||||
|
||||
### रोलबैक योजना
|
||||
मुख्य परिवर्तन पिछड़े संगत हैं - मौजूदा टूल अप्रभावित हैं
|
||||
यदि कोई समस्या उत्पन्न होती है, तो auth-token हैंडलिंग को हेडर बिल्डिंग लॉजिक को हटाकर अक्षम किया जा सकता है
|
||||
CLI परिवर्तन स्वतंत्र हैं और उन्हें अलग से वापस रोल किया जा सकता है
|
||||
|
||||
## सुरक्षा संबंधी विचार
|
||||
|
||||
### ⚠️ महत्वपूर्ण सीमा: केवल सिंगल-टेनेंट प्रमाणीकरण
|
||||
|
||||
**यह प्रमाणीकरण तंत्र मल्टी-यूजर या मल्टी-टेनेंट वातावरण के लिए उपयुक्त नहीं है।**
|
||||
|
||||
**साझा क्रेडेंशियल**: सभी उपयोगकर्ता और इनवोकेशन प्रत्येक MCP टूल के लिए एक ही टोकन साझा करते हैं
|
||||
**कोई उपयोगकर्ता संदर्भ नहीं**: MCP सर्वर विभिन्न TrustGraph उपयोगकर्ताओं के बीच अंतर नहीं कर सकता है
|
||||
**कोई किरायेदार अलगाव नहीं**: सभी किरायेदार प्रत्येक MCP टूल के लिए एक ही क्रेडेंशियल साझा करते हैं
|
||||
**ऑडिट ट्रेल सीमा**: MCP सर्वर लॉग समान क्रेडेंशियल से सभी अनुरोध दिखाते हैं
|
||||
**अनुमति दायरा**: विभिन्न उपयोगकर्ताओं के लिए विभिन्न अनुमति स्तरों को लागू नहीं किया जा सकता है
|
||||
|
||||
**इस सुविधा का उपयोग न करें यदि:**
|
||||
आपका TrustGraph परिनियोजन कई संगठनों (मल्टी-टेनेंट) को सेवा प्रदान करता है
|
||||
आपको यह ट्रैक करने की आवश्यकता है कि किस उपयोगकर्ता ने किस MCP टूल तक पहुंच की
|
||||
विभिन्न उपयोगकर्ताओं को विभिन्न अनुमति स्तरों की आवश्यकता होती है
|
||||
आपको उपयोगकर्ता-स्तरीय ऑडिट आवश्यकताओं का अनुपालन करने की आवश्यकता है
|
||||
आपका MCP सर्वर प्रति-उपयोगकर्ता दर सीमा या कोटा लागू करता है
|
||||
|
||||
**बहु-उपयोगकर्ता/बहु-किरायेदार परिदृश्यों के लिए वैकल्पिक समाधान:**
|
||||
कस्टम हेडर के माध्यम से उपयोगकर्ता संदर्भ का प्रचार लागू करें
|
||||
प्रत्येक किरायेदार के लिए अलग-अलग TrustGraph इंस्टेंस तैनात करें
|
||||
नेटवर्क-स्तरीय अलगाव का उपयोग करें (वीपीसी, सेवा जाल)
|
||||
एक प्रॉक्सी परत लागू करें जो प्रति-उपयोगकर्ता प्रमाणीकरण को संभालती है
|
||||
|
||||
### टोकन भंडारण
|
||||
**जोखिम**: टोकन कॉन्फ़िगरेशन सिस्टम में सादे पाठ में संग्रहीत हैं
|
||||
|
||||
**शमन**:
|
||||
दस्तावेज़ करें कि टोकन एन्क्रिप्टेड के बिना संग्रहीत हैं
|
||||
जहां संभव हो, कम अवधि के टोकन का उपयोग करने की अनुशंसा करें
|
||||
कॉन्फ़िगरेशन भंडारण पर उचित पहुंच नियंत्रण का उपयोग करने की अनुशंसा करें
|
||||
एन्क्रिप्टेड टोकन भंडारण के लिए भविष्य के सुधार पर विचार करें
|
||||
|
||||
### टोकन एक्सपोजर
|
||||
**जोखिम**: टोकन लॉग या CLI आउटपुट में उजागर हो सकते हैं
|
||||
|
||||
**शमन**:
|
||||
टोकन मानों को लॉग न करें (केवल "auth कॉन्फ़िगर किया गया: हाँ/नहीं" लॉग करें)
|
||||
CLI शो कमांड केवल मास्क की स्थिति प्रदर्शित करता है, वास्तविक टोकन नहीं
|
||||
त्रुटि संदेशों में टोकन शामिल न करें
|
||||
|
||||
### नेटवर्क सुरक्षा
|
||||
**जोखिम**: टोकन एन्क्रिप्टेड कनेक्शन पर प्रसारित होते हैं
|
||||
|
||||
**शमन**:
|
||||
MCP सर्वरों के लिए HTTPS URL का उपयोग करने की अनुशंसा करने वाला दस्तावेज़
|
||||
HTTP के साथ प्लेनटेक्स्ट ट्रांसमिशन जोखिम के बारे में उपयोगकर्ताओं को चेतावनी दें
|
||||
|
||||
### कॉन्फ़िगरेशन एक्सेस
|
||||
**जोखिम**: कॉन्फ़िगरेशन सिस्टम तक अनधिकृत पहुंच टोकन को उजागर करती है
|
||||
|
||||
**शमन**:
|
||||
कॉन्फ़िगरेशन सिस्टम एक्सेस को सुरक्षित करने के महत्व का दस्तावेज़ करें
|
||||
कॉन्फ़िगरेशन एक्सेस के लिए न्यूनतम विशेषाधिकार के सिद्धांत की अनुशंसा करें
|
||||
कॉन्फ़िगरेशन परिवर्तनों के लिए ऑडिट लॉगिंग पर विचार करें (भविष्य का सुधार)
|
||||
|
||||
### बहु-उपयोगकर्ता वातावरण
|
||||
**जोखिम**: बहु-उपयोगकर्ता परिनियोजन में, सभी उपयोगकर्ता समान MCP क्रेडेंशियल्स साझा करते हैं
|
||||
|
||||
**जोखिम को समझना**:
|
||||
उपयोगकर्ता ए और उपयोगकर्ता बी दोनों एक ही टोकन का उपयोग MCP टूल तक पहुंचने के लिए करते हैं
|
||||
MCP सर्वर विभिन्न TrustGraph उपयोगकर्ताओं के बीच अंतर नहीं कर सकता है
|
||||
प्रति-उपयोगकर्ता अनुमतियों या दर सीमाओं को लागू करने का कोई तरीका नहीं है
|
||||
MCP सर्वर पर ऑडिट लॉग समान क्रेडेंशियल से सभी अनुरोध दिखाते हैं
|
||||
यदि एक उपयोगकर्ता का सत्र समझौता किया जाता है, तो हमलावर के पास सभी उपयोगकर्ताओं के समान MCP एक्सेस होता है
|
||||
|
||||
**यह कोई बग नहीं है - यह इस डिज़ाइन की एक मूलभूत सीमा है।**
|
||||
|
||||
## प्रदर्शन प्रभाव
|
||||
**न्यूनतम ओवरहेड**: हेडर निर्माण में नगण्य प्रसंस्करण समय लगता है
|
||||
**नेटवर्क प्रभाव**: अतिरिक्त HTTP हेडर प्रति अनुरोध लगभग 50-200 बाइट जोड़ता है
|
||||
**मेमोरी उपयोग**: कॉन्फ़िगरेशन में टोकन स्ट्रिंग को संग्रहीत करने के लिए नगण्य वृद्धि
|
||||
|
||||
## दस्तावेज़
|
||||
|
||||
### उपयोगकर्ता दस्तावेज़
|
||||
[ ] `tg-set-mcp-tool.md` को `--auth-token` पैरामीटर के साथ अपडेट करें
|
||||
[ ] सुरक्षा विचारों अनुभाग जोड़ें
|
||||
[ ] बेयरर टोकन के साथ उपयोग के उदाहरण प्रदान करें
|
||||
[ ] टोकन भंडारण निहितार्थों का दस्तावेज़ करें
|
||||
|
||||
### डेवलपर दस्तावेज़
|
||||
[ ] `service.py` में auth टोकन हैंडलिंग के लिए इनलाइन टिप्पणियाँ जोड़ें
|
||||
[ ] हेडर निर्माण तर्क का दस्तावेज़ करें
|
||||
[ ] MCP टूल कॉन्फ़िगरेशन स्कीमा दस्तावेज़ को अपडेट करें
|
||||
|
||||
## खुले प्रश्न
|
||||
1. **टोकन एन्क्रिप्शन**: क्या हमें कॉन्फ़िगरेशन सिस्टम में एन्क्रिप्टेड टोकन भंडारण लागू करना चाहिए?
|
||||
2. **टोकन रिफ्रेश**: OAuth रिफ्रेश प्रवाह या टोकन रोटेशन के लिए भविष्य का समर्थन?
|
||||
3. **वैकल्पिक auth विधियाँ**: क्या हमें बेसिक auth, API कुंजियाँ, या अन्य विधियों का समर्थन करना चाहिए?
|
||||
|
||||
## विचारे गए विकल्प
|
||||
|
||||
1. **टोकन के लिए पर्यावरण चर**: कॉन्फ़िगरेशन के बजाय env चर में टोकन संग्रहीत करें
|
||||
**अस्वीकृत**: परिनियोजन और कॉन्फ़िगरेशन प्रबंधन को जटिल बनाता है
|
||||
|
||||
2. **अलग सीक्रेट स्टोर**: समर्पित सीक्रेट प्रबंधन प्रणाली का उपयोग करें
|
||||
**स्थगित**: प्रारंभिक कार्यान्वयन के लिए दायरे से बाहर, भविष्य के सुधार पर विचार करें
|
||||
|
||||
3. **एकाधिक auth विधियाँ**: बेसिक, API कुंजी, OAuth, आदि का समर्थन करें
|
||||
**अस्वीकृत**: बेयरर टोकन अधिकांश उपयोग मामलों को कवर करते हैं, प्रारंभिक कार्यान्वयन को सरल रखें
|
||||
|
||||
4. **एन्क्रिप्टेड टोकन भंडारण**: कॉन्फ़िगरेशन सिस्टम में टोकन एन्क्रिप्ट करें
|
||||
**स्थगित**: कॉन्फ़िगरेशन सिस्टम सुरक्षा एक व्यापक चिंता है, भविष्य के कार्य पर स्थगित करें
|
||||
|
||||
5. **प्रति-आवाहन टोकन**: टोकन को आह्वान के समय पास करने की अनुमति दें
|
||||
**अस्वीकृत**: अलगाव के सिद्धांतों का उल्लंघन करता है, एजेंट को क्रेडेंशियल्स को संभालने में नहीं होना चाहिए
|
||||
|
||||
## संदर्भ
|
||||
[MCP प्रोटोकॉल विनिर्देश](https://github.com/modelcontextprotocol/spec)
|
||||
[HTTP बेयरर प्रमाणीकरण (RFC 6750)](https://tools.ietf.org/html/rfc6750)
|
||||
[वर्तमान MCP टूल सेवा](../trustgraph-flow/trustgraph/agent/mcp_tool/service.py)
|
||||
[MCP टूल तर्क विनिर्देश](./mcp-tool-arguments.md)
|
||||
|
||||
## परिशिष्ट
|
||||
|
||||
### उपयोग उदाहरण
|
||||
|
||||
**एमसीपी टूल को प्रमाणीकरण के साथ स्थापित करना**:
|
||||
```bash
|
||||
tg-set-mcp-tool \
|
||||
--id secure-tool \
|
||||
--tool-url https://secure-server.example.com/mcp \
|
||||
--auth-token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
```
|
||||
|
||||
**एमसीपी उपकरणों को प्रदर्शित करना**:
|
||||
```bash
|
||||
tg-show-mcp-tools
|
||||
|
||||
ID Remote Name URL Auth
|
||||
----------- ----------- ------------------------------------ ------
|
||||
secure-tool secure-tool https://secure-server.example.com/mcp Yes
|
||||
public-tool public-tool http://localhost:3000/mcp No
|
||||
```
|
||||
|
||||
### कॉन्फ़िगरेशन का उदाहरण
|
||||
|
||||
**कॉन्फ़िगरेशन प्रणाली में संग्रहीत**:
|
||||
```json
|
||||
{
|
||||
"type": "mcp",
|
||||
"key": "secure-tool",
|
||||
"value": "{\"url\": \"https://secure-server.example.com/mcp\", \"auth-token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"}"
|
||||
}
|
||||
```
|
||||
|
||||
### सुरक्षा सर्वोत्तम अभ्यास
|
||||
|
||||
1. **HTTPS का उपयोग करें**: प्रमाणीकरण वाले MCP सर्वरों के लिए हमेशा HTTPS URL का उपयोग करें।
|
||||
2. **अल्पकालिक टोकन**: जहां संभव हो, समाप्ति तिथि वाले टोकन का उपयोग करें।
|
||||
3. **न्यूनतम विशेषाधिकार**: टोकन को आवश्यक न्यूनतम अनुमतियाँ प्रदान करें।
|
||||
4. **पहुंच नियंत्रण**: कॉन्फ़िगरेशन सिस्टम तक पहुंच को प्रतिबंधित करें।
|
||||
5. **टोकन रोटेशन**: टोकन को नियमित रूप से बदलें।
|
||||
6. **ऑडिट लॉगिंग**: सुरक्षा घटनाओं के लिए कॉन्फ़िगरेशन परिवर्तनों की निगरानी करें।
|
||||
266
docs/tech-specs/hi/minio-to-s3-migration.hi.md
Normal file
266
docs/tech-specs/hi/minio-to-s3-migration.hi.md
Normal file
|
|
@ -0,0 +1,266 @@
|
|||
---
|
||||
layout: default
|
||||
title: "तकनीकी विनिर्देश: S3-संगत स्टोरेज बैकएंड समर्थन"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# तकनीकी विनिर्देश: S3-संगत स्टोरेज बैकएंड समर्थन
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
लाइब्रेरियन सेवा दस्तावेज़ ब्लॉब स्टोरेज के लिए S3-संगत ऑब्जेक्ट स्टोरेज का उपयोग करती है। यह विनिर्देश उस कार्यान्वयन का दस्तावेज़ करता है जो किसी भी S3-संगत बैकएंड के लिए समर्थन को सक्षम करता है, जिसमें MinIO, Ceph RADOS गेटवे (RGW), AWS S3, Cloudflare R2, DigitalOcean Spaces और अन्य शामिल हैं।
|
||||
|
||||
## वास्तुकला
|
||||
|
||||
### स्टोरेज घटक
|
||||
**ब्लॉब स्टोरेज**: `minio` पायथन क्लाइंट लाइब्रेरी के माध्यम से S3-संगत ऑब्जेक्ट स्टोरेज
|
||||
**मेटाडेटा स्टोरेज**: कैसेंड्रा (ऑब्जेक्ट_आईडी मैपिंग और दस्तावेज़ मेटाडेटा संग्रहीत करता है)
|
||||
**प्रभावित घटक**: केवल लाइब्रेरियन सेवा
|
||||
**स्टोरेज पैटर्न**: कैसेंड्रा में मेटाडेटा और S3-संगत स्टोरेज में सामग्री के साथ हाइब्रिड स्टोरेज
|
||||
|
||||
### कार्यान्वयन
|
||||
**लाइब्रेरी**: `minio` पायथन क्लाइंट (किसी भी S3-संगत API का समर्थन करता है)
|
||||
**स्थान**: `trustgraph-flow/trustgraph/librarian/blob_store.py`
|
||||
**ऑपरेशन**:
|
||||
`add()` - UUID ऑब्जेक्ट_आईडी के साथ ब्लॉब संग्रहीत करें
|
||||
`get()` - ऑब्जेक्ट_आईडी द्वारा ब्लॉब पुनर्प्राप्त करें
|
||||
`remove()` - ऑब्जेक्ट_आईडी द्वारा ब्लॉब हटाएं
|
||||
`ensure_bucket()` - यदि मौजूद नहीं है तो बकेट बनाएं
|
||||
**बकेट**: `library`
|
||||
**ऑब्जेक्ट पथ**: `doc/{object_id}`
|
||||
**समर्थित MIME प्रकार**: `text/plain`, `application/pdf`
|
||||
|
||||
### महत्वपूर्ण फाइलें
|
||||
1. `trustgraph-flow/trustgraph/librarian/blob_store.py` - BlobStore कार्यान्वयन
|
||||
2. `trustgraph-flow/trustgraph/librarian/librarian.py` - BlobStore इनिशियलाइज़ेशन
|
||||
3. `trustgraph-flow/trustgraph/librarian/service.py` - सेवा कॉन्फ़िगरेशन
|
||||
4. `trustgraph-flow/pyproject.toml` - निर्भरताएँ (`minio` पैकेज)
|
||||
5. `docs/apis/api-librarian.md` - एपीआई दस्तावेज़
|
||||
|
||||
## समर्थित स्टोरेज बैकएंड
|
||||
|
||||
कार्यान्वयन किसी भी S3-संगत ऑब्जेक्ट स्टोरेज सिस्टम के साथ काम करता है:
|
||||
|
||||
### परीक्षण किया गया/समर्थित
|
||||
**Ceph RADOS गेटवे (RGW)** - S3 API के साथ वितरित स्टोरेज सिस्टम (डिफ़ॉल्ट कॉन्फ़िगरेशन)
|
||||
**MinIO** - हल्का स्व-होस्टेड ऑब्जेक्ट स्टोरेज
|
||||
**गैराज** - हल्का जियो-वितरित S3-संगत स्टोरेज
|
||||
|
||||
### काम करना चाहिए (S3-संगत)
|
||||
**AWS S3** - अमेज़ॅन का क्लाउड ऑब्जेक्ट स्टोरेज
|
||||
**Cloudflare R2** - Cloudflare का S3-संगत स्टोरेज
|
||||
**DigitalOcean Spaces** - DigitalOcean का ऑब्जेक्ट स्टोरेज
|
||||
**Wasabi** - S3-संगत क्लाउड स्टोरेज
|
||||
**Backblaze B2** - S3-संगत बैकअप स्टोरेज
|
||||
S3 REST API को लागू करने वाली कोई भी अन्य सेवा
|
||||
|
||||
## कॉन्फ़िगरेशन
|
||||
|
||||
### CLI तर्क
|
||||
|
||||
```bash
|
||||
librarian \
|
||||
--object-store-endpoint <hostname:port> \
|
||||
--object-store-access-key <access_key> \
|
||||
--object-store-secret-key <secret_key> \
|
||||
[--object-store-use-ssl] \
|
||||
[--object-store-region <region>]
|
||||
```
|
||||
|
||||
**ध्यान दें:** अंतिम बिंदु में `http://` या `https://` को शामिल न करें। HTTPS को सक्षम करने के लिए `--object-store-use-ssl` का उपयोग करें।
|
||||
|
||||
### पर्यावरण चर (वैकल्पिक)
|
||||
|
||||
```bash
|
||||
OBJECT_STORE_ENDPOINT=<hostname:port>
|
||||
OBJECT_STORE_ACCESS_KEY=<access_key>
|
||||
OBJECT_STORE_SECRET_KEY=<secret_key>
|
||||
OBJECT_STORE_USE_SSL=true|false # Optional, default: false
|
||||
OBJECT_STORE_REGION=<region> # Optional
|
||||
```
|
||||
|
||||
### उदाहरण
|
||||
|
||||
**सेफ रेडोस गेटवे (डिफ़ॉल्ट):**
|
||||
```bash
|
||||
--object-store-endpoint ceph-rgw:7480 \
|
||||
--object-store-access-key object-user \
|
||||
--object-store-secret-key object-password
|
||||
```
|
||||
|
||||
**मिनियो:**
|
||||
```bash
|
||||
--object-store-endpoint minio:9000 \
|
||||
--object-store-access-key minioadmin \
|
||||
--object-store-secret-key minioadmin
|
||||
```
|
||||
|
||||
**गैराज (एस3-संगत):**
|
||||
```bash
|
||||
--object-store-endpoint garage:3900 \
|
||||
--object-store-access-key GK000000000000000000000001 \
|
||||
--object-store-secret-key b171f00be9be4c32c734f4c05fe64c527a8ab5eb823b376cfa8c2531f70fc427
|
||||
```
|
||||
|
||||
**AWS S3 एसएसएल के साथ:**
|
||||
```bash
|
||||
--object-store-endpoint s3.amazonaws.com \
|
||||
--object-store-access-key AKIAIOSFODNN7EXAMPLE \
|
||||
--object-store-secret-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
|
||||
--object-store-use-ssl \
|
||||
--object-store-region us-east-1
|
||||
```
|
||||
|
||||
## प्रमाणीकरण
|
||||
|
||||
सभी S3-संगत बैकएंड को AWS सिग्नेचर संस्करण 4 (या v2) प्रमाणीकरण की आवश्यकता होती है:
|
||||
|
||||
**एक्सेस कुंजी** - सार्वजनिक पहचानकर्ता (जैसे उपयोगकर्ता नाम)
|
||||
**सीक्रेट कुंजी** - निजी हस्ताक्षर कुंजी (जैसे पासवर्ड)
|
||||
|
||||
MinIO पायथन क्लाइंट सभी हस्ताक्षर गणना को स्वचालित रूप से संभालता है।
|
||||
|
||||
### क्रेडेंशियल बनाना
|
||||
|
||||
**MinIO के लिए:**
|
||||
```bash
|
||||
# Use default credentials or create user via MinIO Console
|
||||
minioadmin / minioadmin
|
||||
```
|
||||
|
||||
**सेफ आरजीडब्ल्यू के लिए:**
|
||||
```bash
|
||||
radosgw-admin user create --uid="trustgraph" --display-name="TrustGraph Service"
|
||||
# Returns access_key and secret_key
|
||||
```
|
||||
|
||||
**AWS S3 के लिए:**
|
||||
S3 अनुमतियों के साथ एक IAM उपयोगकर्ता बनाएँ।
|
||||
AWS कंसोल में एक्सेस कुंजी उत्पन्न करें।
|
||||
|
||||
## लाइब्रेरी चयन: MinIO Python क्लाइंट
|
||||
|
||||
**तर्क:**
|
||||
हल्का (~500KB बनाम boto3 का ~50MB)
|
||||
S3-संगत - किसी भी S3 API एंडपॉइंट के साथ काम करता है।
|
||||
बुनियादी कार्यों के लिए boto3 की तुलना में सरल API।
|
||||
पहले से उपयोग में है, माइग्रेशन की आवश्यकता नहीं है।
|
||||
MinIO और अन्य S3 सिस्टम के साथ परीक्षण किया गया।
|
||||
|
||||
## BlobStore कार्यान्वयन
|
||||
|
||||
**स्थान:** `trustgraph-flow/trustgraph/librarian/blob_store.py`
|
||||
|
||||
```python
|
||||
from minio import Minio
|
||||
import io
|
||||
import logging
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
class BlobStore:
|
||||
"""
|
||||
S3-compatible blob storage for document content.
|
||||
Supports MinIO, Ceph RGW, AWS S3, and other S3-compatible backends.
|
||||
"""
|
||||
|
||||
def __init__(self, endpoint, access_key, secret_key, bucket_name,
|
||||
use_ssl=False, region=None):
|
||||
"""
|
||||
Initialize S3-compatible blob storage.
|
||||
|
||||
Args:
|
||||
endpoint: S3 endpoint (e.g., "minio:9000", "ceph-rgw:7480")
|
||||
access_key: S3 access key
|
||||
secret_key: S3 secret key
|
||||
bucket_name: Bucket name for storage
|
||||
use_ssl: Use HTTPS instead of HTTP (default: False)
|
||||
region: S3 region (optional, e.g., "us-east-1")
|
||||
"""
|
||||
self.client = Minio(
|
||||
endpoint=endpoint,
|
||||
access_key=access_key,
|
||||
secret_key=secret_key,
|
||||
secure=use_ssl,
|
||||
region=region,
|
||||
)
|
||||
|
||||
self.bucket_name = bucket_name
|
||||
|
||||
protocol = "https" if use_ssl else "http"
|
||||
logger.info(f"Connected to S3-compatible storage at {protocol}://{endpoint}")
|
||||
|
||||
self.ensure_bucket()
|
||||
|
||||
def ensure_bucket(self):
|
||||
"""Create bucket if it doesn't exist"""
|
||||
found = self.client.bucket_exists(bucket_name=self.bucket_name)
|
||||
if not found:
|
||||
self.client.make_bucket(bucket_name=self.bucket_name)
|
||||
logger.info(f"Created bucket {self.bucket_name}")
|
||||
else:
|
||||
logger.debug(f"Bucket {self.bucket_name} already exists")
|
||||
|
||||
async def add(self, object_id, blob, kind):
|
||||
"""Store blob in S3-compatible storage"""
|
||||
self.client.put_object(
|
||||
bucket_name=self.bucket_name,
|
||||
object_name=f"doc/{object_id}",
|
||||
length=len(blob),
|
||||
data=io.BytesIO(blob),
|
||||
content_type=kind,
|
||||
)
|
||||
logger.debug("Add blob complete")
|
||||
|
||||
async def remove(self, object_id):
|
||||
"""Delete blob from S3-compatible storage"""
|
||||
self.client.remove_object(
|
||||
bucket_name=self.bucket_name,
|
||||
object_name=f"doc/{object_id}",
|
||||
)
|
||||
logger.debug("Remove blob complete")
|
||||
|
||||
async def get(self, object_id):
|
||||
"""Retrieve blob from S3-compatible storage"""
|
||||
resp = self.client.get_object(
|
||||
bucket_name=self.bucket_name,
|
||||
object_name=f"doc/{object_id}",
|
||||
)
|
||||
return resp.read()
|
||||
```
|
||||
|
||||
## मुख्य लाभ
|
||||
|
||||
1. **कोई विक्रेता लॉक-इन नहीं** - किसी भी S3-संगत स्टोरेज के साथ काम करता है।
|
||||
2. **हल्का** - MinIO क्लाइंट केवल ~500KB है।
|
||||
3. **सरल कॉन्फ़िगरेशन** - केवल एंडपॉइंट + क्रेडेंशियल।
|
||||
4. **कोई डेटा माइग्रेशन नहीं** - बैकएंड के बीच ड्रॉप-इन रिप्लेसमेंट।
|
||||
5. **युद्ध-परीक्षित** - MinIO क्लाइंट सभी प्रमुख S3 कार्यान्वयन के साथ काम करता है।
|
||||
|
||||
## कार्यान्वयन स्थिति
|
||||
|
||||
सभी कोड को जेनेरिक S3 पैरामीटर नामों का उपयोग करने के लिए अपडेट किया गया है:
|
||||
|
||||
✅ `blob_store.py` - `endpoint`, `access_key`, `secret_key` को स्वीकार करने के लिए अपडेट किया गया।
|
||||
✅ `librarian.py` - पैरामीटर नामों को अपडेट किया गया।
|
||||
✅ `service.py` - CLI तर्क और कॉन्फ़िगरेशन को अपडेट किया गया।
|
||||
✅ दस्तावेज़ अपडेट किया गया।
|
||||
|
||||
## भविष्य के सुधार
|
||||
|
||||
1. **SSL/TLS समर्थन** - HTTPS के लिए `--s3-use-ssl` ध्वज जोड़ें।
|
||||
2. **पुन: प्रयास तर्क** - क्षणिक विफलताओं के लिए घातीय बैकऑफ़ लागू करें।
|
||||
3. **प्रीसाइंड URL** - अस्थायी अपलोड/डाउनलोड URL उत्पन्न करें।
|
||||
4. **मल्टी-रीजन समर्थन** - क्षेत्रों में ब्लॉब्स को दोहराएं।
|
||||
5. **CDN एकीकरण** - CDN के माध्यम से ब्लॉब्स परोसें।
|
||||
6. **स्टोरेज क्लासेस** - लागत अनुकूलन के लिए S3 स्टोरेज क्लासेस का उपयोग करें।
|
||||
7. **लाइफसाइकिल नीतियां** - स्वचालित अभिलेखागार/हटाना।
|
||||
8. **वर्जनिंग** - ब्लॉब्स के कई संस्करणों को संग्रहीत करें।
|
||||
|
||||
## संदर्भ
|
||||
|
||||
MinIO Python क्लाइंट: https://min.io/docs/minio/linux/developers/python/API.html
|
||||
Ceph RGW S3 API: https://docs.ceph.com/en/latest/radosgw/s3/
|
||||
S3 API संदर्भ: https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html
|
||||
203
docs/tech-specs/hi/more-config-cli.hi.md
Normal file
203
docs/tech-specs/hi/more-config-cli.hi.md
Normal file
|
|
@ -0,0 +1,203 @@
|
|||
---
|
||||
layout: default
|
||||
title: "अधिक कॉन्फ़िगरेशन CLI तकनीकी विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
```hindi
|
||||
# अधिक कॉन्फ़िगरेशन CLI तकनीकी विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह विनिर्देश TrustGraph के लिए उन्नत कमांड-लाइन कॉन्फ़िगरेशन क्षमताओं का वर्णन करता है, जो उपयोगकर्ताओं को दानेदार CLI कमांड के माध्यम से व्यक्तिगत कॉन्फ़िगरेशन आइटम प्रबंधित करने की अनुमति देता है। यह एकीकरण चार प्राथमिक उपयोग मामलों का समर्थन करता है:
|
||||
|
||||
1. **कॉन्फ़िगरेशन आइटमों की सूची**: किसी विशिष्ट प्रकार की कॉन्फ़िगरेशन कुंजियों का प्रदर्शन करें।
|
||||
2. **कॉन्फ़िगरेशन आइटम प्राप्त करें**: विशिष्ट कॉन्फ़िगरेशन मान पुनः प्राप्त करें।
|
||||
3. **कॉन्फ़िगरेशन आइटम सेट करें**: व्यक्तिगत कॉन्फ़िगरेशन आइटम सेट या अपडेट करें।
|
||||
4. **कॉन्फ़िगरेशन आइटम हटाएं**: विशिष्ट कॉन्फ़िगरेशन आइटम हटाएं।
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
- **बारीक नियंत्रण**: व्यक्तिगत कॉन्फ़िगरेशन आइटमों के प्रबंधन को सक्षम करें, न कि बल्क ऑपरेशनों को।
|
||||
- **प्रकार-आधारित सूची**: उपयोगकर्ताओं को कॉन्फ़िगरेशन आइटमों को प्रकार के अनुसार ब्राउज़ करने की अनुमति दें।
|
||||
- **एकल आइटम संचालन**: व्यक्तिगत कॉन्फ़िगरेशन आइटमों के लिए प्राप्त/सेट/हटाने के कमांड प्रदान करें।
|
||||
- **API एकीकरण**: सभी परिचालनों के लिए मौजूदा कॉन्फ़िगरेशन API का उपयोग करें।
|
||||
- **संगत CLI पैटर्न**: स्थापित TrustGraph CLI कन्वेंशन और पैटर्न का पालन करें।
|
||||
- **त्रुटि प्रबंधन**: अमान्य परिचालनों के लिए स्पष्ट त्रुटि संदेश प्रदान करें।
|
||||
- **JSON आउटपुट**: प्रोग्रामेटिक उपयोग के लिए संरचित आउटपुट का समर्थन करें।
|
||||
- **प्रलेखन**: व्यापक सहायता और उपयोग उदाहरण शामिल करें।
|
||||
|
||||
## पृष्ठभूमि
|
||||
|
||||
TrustGraph वर्तमान में कॉन्फ़िगरेशन API और एक एकल CLI कमांड `tg-show-config` के माध्यम से कॉन्फ़िगरेशन प्रबंधन प्रदान करता है जो संपूर्ण कॉन्फ़िगरेशन प्रदर्शित करता है। जबकि यह कॉन्फ़िगरेशन देखने के लिए उपयोगी है, यह दानेदार प्रबंधन क्षमताओं की कमी है।
|
||||
|
||||
वर्तमान सीमाएँ शामिल हैं:
|
||||
- CLI से प्रकार के अनुसार कॉन्फ़िगरेशन आइटमों की सूची बनाने का कोई तरीका नहीं है।
|
||||
- विशिष्ट कॉन्फ़िगरेशन मान पुनः प्राप्त करने के लिए कोई CLI कमांड नहीं है।
|
||||
- व्यक्तिगत कॉन्फ़िगरेशन आइटमों को सेट करने के लिए कोई CLI कमांड नहीं है।
|
||||
- विशिष्ट कॉन्फ़िगरेशन आइटमों को हटाने के लिए कोई CLI कमांड नहीं है।
|
||||
|
||||
यह विनिर्देश इन कमियों को चार नए CLI कमांड जोड़कर संबोधित करता है जो दानेदार कॉन्फ़िगरेशन प्रबंधन प्रदान करते हैं। TrustGraph, CLI कमांड के माध्यम से व्यक्तिगत कॉन्फ़िगरेशन API परिचालनों को उजागर करके:
|
||||
- स्क्रिप्टेड कॉन्फ़िगरेशन प्रबंधन को सक्षम करें।
|
||||
- प्रकार के अनुसार कॉन्फ़िगरेशन संरचना की खोज की अनुमति दें।
|
||||
- लक्षित कॉन्फ़िगरेशन अपडेट का समर्थन करें।
|
||||
- कॉन्फ़िगरेशन नियंत्रण का महीन स्तर प्रदान करें।
|
||||
|
||||
## तकनीकी डिजाइन
|
||||
|
||||
### आर्किटेक्चर
|
||||
|
||||
उन्नत CLI कॉन्फ़िगरेशन के लिए निम्नलिखित तकनीकी घटकों की आवश्यकता होती है:
|
||||
|
||||
1. **tg-list-config-items**
|
||||
- एक निर्दिष्ट प्रकार के लिए कॉन्फ़िगरेशन कुंजियों की सूची बनाता है।
|
||||
- `Config.list(type)` API विधि को कॉल करता है।
|
||||
- कॉन्फ़िगरेशन कुंजियों की सूची आउटपुट करता है।
|
||||
|
||||
मॉड्यूल: `trustgraph.cli.list_config_items`
|
||||
|
||||
2. **tg-get-config-item**
|
||||
- विशिष्ट कॉन्फ़िगरेशन आइटम(ों) को पुनः प्राप्त करता है।
|
||||
- `Config.get(keys)` API विधि को कॉल करता है।
|
||||
- कॉन्फ़िगरेशन मानों को JSON प्रारूप में आउटपुट करता है।
|
||||
|
||||
मॉड्यूल: `trustgraph.cli.get_config_item`
|
||||
|
||||
3. **tg-put-config-item**
|
||||
- एक कॉन्फ़िगरेशन आइटम सेट या अपडेट करता है।
|
||||
- `Config.put(values)` API विधि को कॉल करता है।
|
||||
- प्रकार, कुंजी और मान पैरामीटर स्वीकार करता है।
|
||||
|
||||
मॉड्यूल: `trustgraph.cli.put_config_item`
|
||||
|
||||
4. **tg-delete-config-item**
|
||||
- एक कॉन्फ़िगरेशन आइटम हटाता है।
|
||||
- `Config.delete(keys)` API विधि को कॉल करता है।
|
||||
- प्रकार और कुंजी पैरामीटर स्वीकार करता है।
|
||||
|
||||
मॉड्यूल: `trustgraph.cli.delete_config_item`
|
||||
|
||||
### डेटा मॉडल
|
||||
|
||||
#### ConfigKey और ConfigValue
|
||||
|
||||
कमांड `trustgraph.api.types` से मौजूदा डेटा संरचनाओं का उपयोग करते हैं:
|
||||
|
||||
```python
|
||||
@dataclasses.dataclass
|
||||
class ConfigKey:
|
||||
type : str
|
||||
key : str
|
||||
|
||||
@dataclasses.dataclass
|
||||
class ConfigValue:
|
||||
type : str
|
||||
key : str
|
||||
value : str
|
||||
```
|
||||
|
||||
यह दृष्टिकोण अनुमति देता है:
|
||||
- CLI और API में सुसंगत डेटा प्रबंधन।
|
||||
- प्रकार-सुरक्षित कॉन्फ़िगरेशन संचालन।
|
||||
- संरचित इनपुट/आउटपुट प्रारूप।
|
||||
- मौजूदा कॉन्फ़िगरेशन API के साथ एकीकरण।
|
||||
|
||||
### CLI कमांड विनिर्देश
|
||||
|
||||
#### tg-list-config-items
|
||||
```bash
|
||||
tg-list-config-items --type <config-type> [--format text|json] [--api-url <url>]
|
||||
```
|
||||
- **उद्देश्य**: एक दिए गए प्रकार के सभी कॉन्फ़िगरेशन कुंजियों की सूची बनाएं।
|
||||
- **API कॉल**: `Config.list(type)`
|
||||
- **आउटपुट**:
|
||||
- `text` (डिफ़ॉल्ट): कॉन्फ़िगरेशन कुंजियाँ नई पंक्तियों से अलग की गई हैं।
|
||||
- `json`: कॉन्फ़िगरेशन कुंजियों की JSON सरणी।
|
||||
|
||||
#### tg-get-config-item
|
||||
```bash
|
||||
tg-get-config-item --type <type> --key <key> [--format text|json] [--api-url <url>]
|
||||
```
|
||||
- **उद्देश्य**: एक विशिष्ट कॉन्फ़िगरेशन आइटम पुनः प्राप्त करें।
|
||||
- **API कॉल**: `Config.get([ConfigKey(type, key)])`
|
||||
- **आउटपुट**:
|
||||
- `text` (डिफ़ॉल्ट): कच्चा स्ट्रिंग मान।
|
||||
- `json`: JSON-एन्कोडेड स्ट्रिंग मान।
|
||||
|
||||
#### tg-put-config-item
|
||||
```bash
|
||||
tg-put-config-item --type <type> --key <key> --value <value> [--api-url <url>]
|
||||
tg-put-config-item --type <type> --key <key> --stdin [--api-url <url>]
|
||||
```
|
||||
- **उद्देश्य**: एक कॉन्फ़िगरेशन आइटम सेट करें।
|
||||
- **API कॉल**: `Config.put(values)`
|
||||
- **पैरामीटर**: प्रकार, कुंजी और मान।
|
||||
- **इनपुट**: कमांड लाइन या stdin के माध्यम से।
|
||||
|
||||
#### tg-delete-config-item
|
||||
```bash
|
||||
tg-delete-config-item --type prompt --key old-template
|
||||
```
|
||||
- **उद्देश्य**: एक कॉन्फ़िगरेशन आइटम हटाएं।
|
||||
- **API कॉल**: `Config.delete(keys)`
|
||||
- **पैरामीटर**: प्रकार और कुंजी।
|
||||
|
||||
## उपयोग उदाहरण
|
||||
|
||||
#### कॉन्फ़िगरेशन आइटमों की सूची
|
||||
```bash
|
||||
# प्रॉम्प्ट कुंजियों की सूची (टेक्स्ट प्रारूप)
|
||||
tg-list-config-items --type prompt
|
||||
template-1
|
||||
template-2
|
||||
system-prompt
|
||||
|
||||
# प्रॉम्प्ट कुंजियों की सूची (JSON प्रारूप)
|
||||
tg-list-config-items --type prompt --format json
|
||||
["template-1", "template-2", "system-prompt"]
|
||||
```
|
||||
|
||||
#### कॉन्फ़िगरेशन आइटम प्राप्त करें
|
||||
```bash
|
||||
# प्रॉम्प्ट मान प्राप्त करें (टेक्स्ट प्रारूप)
|
||||
tg-get-config-item --type prompt --key template-1
|
||||
You are a helpful assistant. Please respond to: {query}
|
||||
|
||||
# प्रॉम्प्ट मान प्राप्त करें (JSON प्रारूप)
|
||||
tg-get-config-item --type prompt --key template-1 --format json
|
||||
"You are a helpful assistant. Please respond to: {query}"
|
||||
```
|
||||
|
||||
#### कॉन्फ़िगरेशन आइटम सेट करें
|
||||
```bash
|
||||
# कमांड लाइन से सेट करें
|
||||
tg-put-config-item --type prompt --key new-template --value "Custom prompt: {input}"
|
||||
|
||||
# फ़ाइल से पाइप के माध्यम से सेट करें
|
||||
cat ./prompt-template.txt | tg-put-config-item --type prompt --key complex-template --stdin
|
||||
|
||||
# फ़ाइल से रीडायरेक्ट के माध्यम से सेट करें
|
||||
tg-put-config-item --type prompt --key complex-template --stdin < ./prompt-template.txt
|
||||
|
||||
# कमांड आउटपुट से सेट करें
|
||||
echo "Generated template: {query}" | tg-put-config-item --type prompt --key auto-template --stdin
|
||||
```
|
||||
|
||||
#### कॉन्फ़िगरेशन आइटम हटाएं
|
||||
```bash
|
||||
tg-delete-config-item --type prompt --key old-template
|
||||
```
|
||||
|
||||
## खुले प्रश्न
|
||||
|
||||
- क्या कमांड एकल आइटमों के अलावा बैच संचालन (एकाधिक कुंजियाँ) का समर्थन करना चाहिए?
|
||||
- सफलता की पुष्टि के लिए किस आउटपुट प्रारूप का उपयोग किया जाना चाहिए?
|
||||
- उपयोगकर्ताओं द्वारा कॉन्फ़िगरेशन प्रकारों का दस्तावेजीकरण/खोज कैसे किया जाना चाहिए?
|
||||
|
||||
## संदर्भ
|
||||
|
||||
- मौजूदा कॉन्फ़िगरेशन API: `trustgraph/api/config.py`
|
||||
- CLI पैटर्न: `trustgraph-cli/trustgraph/cli/show_config.py`
|
||||
- डेटा प्रकार: `trustgraph/api/types.py`
|
||||
780
docs/tech-specs/hi/multi-tenant-support.hi.md
Normal file
780
docs/tech-specs/hi/multi-tenant-support.hi.md
Normal file
|
|
@ -0,0 +1,780 @@
|
|||
---
|
||||
layout: default
|
||||
title: "तकनीकी विनिर्देश: मल्टी-टेनेंट समर्थन"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# तकनीकी विनिर्देश: मल्टी-टेनेंट समर्थन
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
पैरामीटर नाम विसंगतियों को ठीक करके मल्टी-टेनेंट परिनियोजन सक्षम करें जो कतार अनुकूलन को रोकते हैं, और कैसेंड्रा कीस्पेस पैरामीटराइज़ेशन जोड़ें।
|
||||
|
||||
## आर्किटेक्चर संदर्भ
|
||||
|
||||
### फ्लो-आधारित कतार समाधान
|
||||
|
||||
ट्रस्टग्राफ सिस्टम गतिशील कतार समाधान के लिए एक **फ्लो-आधारित आर्किटेक्चर** का उपयोग करता है, जो स्वाभाविक रूप से मल्टी-टेनेंसी का समर्थन करता है:
|
||||
|
||||
**फ्लो परिभाषाएँ** कैसेंड्रा में संग्रहीत हैं और इंटरफ़ेस परिभाषाओं के माध्यम से कतार नामों को निर्दिष्ट करती हैं।
|
||||
**कतार नाम टेम्प्लेट का उपयोग करते हैं** जिसमें `{id}` चर होते हैं जिन्हें फ्लो इंस्टेंस आईडी के साथ प्रतिस्थापित किया जाता है।
|
||||
**सेवाएँ गतिशील रूप से कतारों को हल करती हैं** अनुरोध समय पर फ्लो कॉन्फ़िगरेशन की खोज करके।
|
||||
**प्रत्येक किरायेदार के पास अलग-अलग कतार नामों के साथ अद्वितीय फ्लो हो सकते हैं**, जो अलगाव प्रदान करते हैं।
|
||||
|
||||
फ्लो इंटरफ़ेस परिभाषा का उदाहरण:
|
||||
```json
|
||||
{
|
||||
"interfaces": {
|
||||
"triples-store": "persistent://tg/flow/triples-store:{id}",
|
||||
"graph-embeddings-store": "persistent://tg/flow/graph-embeddings-store:{id}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
जब किरायेदार ए प्रवाह `tenant-a-prod` शुरू करता है और किरायेदार बी प्रवाह `tenant-b-prod` शुरू करता है, तो उन्हें स्वचालित रूप से अलग-अलग कतारें मिलती हैं:
|
||||
`persistent://tg/flow/triples-store:tenant-a-prod`
|
||||
`persistent://tg/flow/triples-store:tenant-b-prod`
|
||||
|
||||
**मल्टी-टेनेंसी के लिए सही ढंग से डिज़ाइन की गई सेवाएं:**
|
||||
✅ **नॉलेज मैनेजमेंट (कोर)** - अनुरोधों में पारित प्रवाह कॉन्फ़िगरेशन से कतारों को गतिशील रूप से हल करता है
|
||||
|
||||
**जिन सेवाओं को ठीक करने की आवश्यकता है:**
|
||||
🔴 **कॉन्फ़िग सर्विस** - पैरामीटर नाम बेमेल होने से कतार अनुकूलन में बाधा आती है
|
||||
🔴 **लाइब्रेरियन सर्विस** - हार्डकोडेड स्टोरेज मैनेजमेंट टॉपिक (नीचे चर्चा की गई है)
|
||||
🔴 **सभी सेवाएं** - कैसेंड्रा कीस्पेस को अनुकूलित नहीं किया जा सकता है
|
||||
|
||||
## समस्या विवरण
|
||||
|
||||
### मुद्दा #1: एसिंक्रोनसप्रोसेसर में पैरामीटर नाम बेमेल
|
||||
**CLI द्वारा परिभाषित:** `--config-queue` (अस्पष्ट नामकरण)
|
||||
**Argparse द्वारा रूपांतरण:** `config_queue` (पैरामीटर डिक्ट में)
|
||||
**कोड द्वारा खोजा गया:** `config_push_queue`
|
||||
**परिणाम:** पैरामीटर को अनदेखा किया जाता है, डिफ़ॉल्ट रूप से `persistent://tg/config/config`
|
||||
**प्रभाव:** 32 से अधिक सेवाओं पर प्रभाव पड़ता है जो AsyncProcessor से विरासत में मिली हैं
|
||||
**बाधा:** मल्टी-टेनेंट डिप्लॉयमेंट किरायेदार-विशिष्ट कॉन्फ़िग कतारों का उपयोग नहीं कर सकते हैं
|
||||
**समाधान:** स्पष्टता के लिए CLI पैरामीटर का नाम बदलकर `--config-push-queue` करें (ब्रेकिंग चेंज स्वीकार्य है क्योंकि सुविधा वर्तमान में टूटी हुई है)
|
||||
|
||||
### मुद्दा #2: कॉन्फ़िग सर्विस में पैरामीटर नाम बेमेल
|
||||
**CLI द्वारा परिभाषित:** `--push-queue` (अस्पष्ट नामकरण)
|
||||
**Argparse द्वारा रूपांतरण:** `push_queue` (पैरामीटर डिक्ट में)
|
||||
**कोड द्वारा खोजा गया:** `config_push_queue`
|
||||
**परिणाम:** पैरामीटर को अनदेखा किया जाता है
|
||||
**प्रभाव:** कॉन्फ़िग सर्विस कस्टम पुश कतार का उपयोग नहीं कर सकती है
|
||||
**समाधान:** स्थिरता और स्पष्टता के लिए CLI पैरामीटर का नाम बदलकर `--config-push-queue` करें (ब्रेकिंग चेंज स्वीकार्य है)
|
||||
|
||||
### मुद्दा #3: हार्डकोडेड कैसेंड्रा कीस्पेस
|
||||
**वर्तमान:** विभिन्न सेवाओं में कीस्पेस को हार्डकोडेड के रूप में `"config"`, `"knowledge"`, `"librarian"` के रूप में परिभाषित किया गया है
|
||||
**परिणाम:** मल्टी-टेनेंट डिप्लॉयमेंट के लिए कीस्पेस को अनुकूलित नहीं किया जा सकता है
|
||||
**प्रभाव:** कॉन्फ़िग, कोर और लाइब्रेरियन सेवाएं
|
||||
**बाधा:** कई किरायेदार अलग-अलग कैसेंड्रा कीस्पेस का उपयोग नहीं कर सकते हैं
|
||||
|
||||
### मुद्दा #4: कलेक्शन मैनेजमेंट आर्किटेक्चर ✅ पूर्ण
|
||||
**पिछला:** कलेक्शन को लाइब्रेरियन कीस्पेस में एक अलग कलेक्शन टेबल के माध्यम से संग्रहीत किया जाता था
|
||||
**पिछला:** लाइब्रेरियन ने कलेक्शन बनाने/हटाने के लिए 4 हार्डकोडेड स्टोरेज मैनेजमेंट टॉपिक का उपयोग किया:
|
||||
`vector_storage_management_topic`
|
||||
`object_storage_management_topic`
|
||||
`triples_storage_management_topic`
|
||||
`storage_management_response_topic`
|
||||
**समस्याएं (हल की गई):**
|
||||
हार्डकोडेड टॉपिक को मल्टी-टेनेंट डिप्लॉयमेंट के लिए अनुकूलित नहीं किया जा सकता था
|
||||
लाइब्रेरियन और 4+ स्टोरेज सेवाओं के बीच जटिल एसिंक्रोनस समन्वय
|
||||
अलग कैसेंड्रा टेबल और प्रबंधन अवसंरचना
|
||||
महत्वपूर्ण कार्यों के लिए गैर-स्थायी अनुरोध/प्रतिक्रिया कतारें
|
||||
**कार्यान्वित समाधान:** कलेक्शन को कॉन्फ़िग सर्विस स्टोरेज में माइग्रेट किया गया, वितरण के लिए कॉन्फ़िग पुश का उपयोग किया गया
|
||||
**स्थिति:** सभी स्टोरेज बैकएंड को `CollectionConfigHandler` पैटर्न में माइग्रेट किया गया है
|
||||
|
||||
## समाधान
|
||||
|
||||
यह विनिर्देश मुद्दों #1, #2, #3 और #4 को संबोधित करता है।
|
||||
|
||||
### भाग 1: पैरामीटर नाम बेमेल को ठीक करें
|
||||
|
||||
#### परिवर्तन 1: AsyncProcessor बेस क्लास - CLI पैरामीटर का नाम बदलें
|
||||
**फ़ाइल:** `trustgraph-base/trustgraph/base/async_processor.py`
|
||||
**पंक्ति:** 260-264
|
||||
|
||||
**वर्तमान:**
|
||||
```python
|
||||
parser.add_argument(
|
||||
'--config-queue',
|
||||
default=default_config_queue,
|
||||
help=f'Config push queue {default_config_queue}',
|
||||
)
|
||||
```
|
||||
|
||||
**निश्चित:**
|
||||
```python
|
||||
parser.add_argument(
|
||||
'--config-push-queue',
|
||||
default=default_config_queue,
|
||||
help=f'Config push queue (default: {default_config_queue})',
|
||||
)
|
||||
```
|
||||
|
||||
**तर्क:**
|
||||
अधिक स्पष्ट और विस्तृत नामकरण
|
||||
आंतरिक चर नाम से मेल खाता है `config_push_queue`
|
||||
परिवर्तन स्वीकार्य है क्योंकि सुविधा वर्तमान में गैर-कार्यात्मक है
|
||||
params.get() में कोई कोड परिवर्तन आवश्यक नहीं है - यह पहले से ही सही नाम की तलाश करता है
|
||||
|
||||
#### परिवर्तन 2: कॉन्फ़िगरेशन सेवा - CLI पैरामीटर का नाम बदलें
|
||||
**फ़ाइल:** `trustgraph-flow/trustgraph/config/service/service.py`
|
||||
**पंक्ति:** 276-279
|
||||
|
||||
**वर्तमान:**
|
||||
```python
|
||||
parser.add_argument(
|
||||
'--push-queue',
|
||||
default=default_config_push_queue,
|
||||
help=f'Config push queue (default: {default_config_push_queue})'
|
||||
)
|
||||
```
|
||||
|
||||
**निश्चित:**
|
||||
```python
|
||||
parser.add_argument(
|
||||
'--config-push-queue',
|
||||
default=default_config_push_queue,
|
||||
help=f'Config push queue (default: {default_config_push_queue})'
|
||||
)
|
||||
```
|
||||
|
||||
**तर्क:**
|
||||
अधिक स्पष्ट नामकरण - "config-push-queue" केवल "push-queue" से अधिक स्पष्ट है।
|
||||
आंतरिक चर नाम `config_push_queue` से मेल खाता है।
|
||||
AsyncProcessor के `--config-push-queue` पैरामीटर के साथ संगत।
|
||||
परिवर्तन स्वीकार्य है क्योंकि सुविधा वर्तमान में गैर-कार्यात्मक है।
|
||||
params.get() में कोई कोड परिवर्तन आवश्यक नहीं है - यह पहले से ही सही नाम की तलाश करता है।
|
||||
|
||||
### भाग 2: कैसेंड्रा कीस्पेस पैरामीटराइज़ेशन जोड़ें
|
||||
|
||||
#### परिवर्तन 3: cassandra_config मॉड्यूल में कीस्पेस पैरामीटर जोड़ें
|
||||
**फ़ाइल:** `trustgraph-base/trustgraph/base/cassandra_config.py`
|
||||
|
||||
**CLI तर्क जोड़ें** (`add_cassandra_args()` फ़ंक्शन में):
|
||||
```python
|
||||
parser.add_argument(
|
||||
'--cassandra-keyspace',
|
||||
default=None,
|
||||
help='Cassandra keyspace (default: service-specific)'
|
||||
)
|
||||
```
|
||||
|
||||
**पर्यावरण चर समर्थन जोड़ें** (फ़ंक्शन `resolve_cassandra_config()` में):
|
||||
```python
|
||||
keyspace = params.get(
|
||||
"cassandra_keyspace",
|
||||
os.environ.get("CASSANDRA_KEYSPACE")
|
||||
)
|
||||
```
|
||||
|
||||
**`resolve_cassandra_config()` का रिटर्न वैल्यू अपडेट करें:**
|
||||
वर्तमान में रिटर्न करता है: `(hosts, username, password)`
|
||||
बदलने पर रिटर्न करेगा: `(hosts, username, password, keyspace)`
|
||||
|
||||
**तर्क:**
|
||||
मौजूदा कैसेंड्रा कॉन्फ़िगरेशन पैटर्न के अनुरूप
|
||||
`add_cassandra_args()` के माध्यम से सभी सेवाओं के लिए उपलब्ध
|
||||
CLI और पर्यावरण चर कॉन्फ़िगरेशन दोनों का समर्थन करता है
|
||||
|
||||
#### परिवर्तन 4: कॉन्फ़िगरेशन सर्विस - पैरामीटराइज़्ड कीस्पेस का उपयोग करें
|
||||
**फ़ाइल:** `trustgraph-flow/trustgraph/config/service/service.py`
|
||||
|
||||
**पंक्ति 30** - हार्डकोडेड कीस्पेस हटाएं:
|
||||
```python
|
||||
# DELETE THIS LINE:
|
||||
keyspace = "config"
|
||||
```
|
||||
|
||||
**पंक्तियाँ 69-73** - कैसेंड्रा कॉन्फ़िगरेशन रिज़ॉल्यूशन को अपडेट करें:
|
||||
|
||||
**वर्तमान:**
|
||||
```python
|
||||
cassandra_host, cassandra_username, cassandra_password = \
|
||||
resolve_cassandra_config(params)
|
||||
```
|
||||
|
||||
**निश्चित:**
|
||||
```python
|
||||
cassandra_host, cassandra_username, cassandra_password, keyspace = \
|
||||
resolve_cassandra_config(params, default_keyspace="config")
|
||||
```
|
||||
|
||||
**तर्क:**
|
||||
"config" को डिफ़ॉल्ट के रूप में रखते हुए पिछली अनुकूलता बनाए रखता है।
|
||||
`--cassandra-keyspace` या `CASSANDRA_KEYSPACE` के माध्यम से ओवरराइड करने की अनुमति देता है।
|
||||
|
||||
#### परिवर्तन 5: कोर/नॉलेज सर्विस - पैरामीटराइज़्ड कीस्पेस का उपयोग करें।
|
||||
**फ़ाइल:** `trustgraph-flow/trustgraph/cores/service.py`
|
||||
|
||||
**पंक्ति 37** - हार्डकोडेड कीस्पेस को हटाएँ:
|
||||
```python
|
||||
# DELETE THIS LINE:
|
||||
keyspace = "knowledge"
|
||||
```
|
||||
|
||||
**कैसेंड्रा कॉन्फ़िगरेशन रिज़ॉल्यूशन को अपडेट करें** (कॉन्फ़िगरेशन सेवा के समान स्थान पर):
|
||||
```python
|
||||
cassandra_host, cassandra_username, cassandra_password, keyspace = \
|
||||
resolve_cassandra_config(params, default_keyspace="knowledge")
|
||||
```
|
||||
|
||||
#### परिवर्तन 6: लाइब्रेरियन सेवा - पैरामीटराइज़्ड कीस्पेस का उपयोग करें
|
||||
**फ़ाइल:** `trustgraph-flow/trustgraph/librarian/service.py`
|
||||
|
||||
**पंक्ति 51** - हार्डकोडेड कीस्पेस हटाएं:
|
||||
```python
|
||||
# DELETE THIS LINE:
|
||||
keyspace = "librarian"
|
||||
```
|
||||
|
||||
**कैसेंड्रा कॉन्फ़िगरेशन रिज़ॉल्यूशन को अपडेट करें** (कॉन्फ़िगरेशन सेवा के समान स्थान पर):
|
||||
```python
|
||||
cassandra_host, cassandra_username, cassandra_password, keyspace = \
|
||||
resolve_cassandra_config(params, default_keyspace="librarian")
|
||||
```
|
||||
|
||||
### भाग 3: संग्रह प्रबंधन को कॉन्फ़िगरेशन सेवा में स्थानांतरित करें
|
||||
|
||||
#### अवलोकन
|
||||
संग्रहों को कैसेंड्रा लाइब्रेरियन कीस्पेस से कॉन्फ़िगरेशन सेवा भंडारण में स्थानांतरित करें। यह हार्ड-कोडेड भंडारण प्रबंधन विषयों को समाप्त करता है और मौजूदा कॉन्फ़िगरेशन पुश तंत्र का उपयोग करके वितरण के लिए वास्तुकला को सरल बनाता है।
|
||||
|
||||
#### वर्तमान वास्तुकला
|
||||
```
|
||||
API Request → Gateway → Librarian Service
|
||||
↓
|
||||
CollectionManager
|
||||
↓
|
||||
Cassandra Collections Table (librarian keyspace)
|
||||
↓
|
||||
Broadcast to 4 Storage Management Topics (hardcoded)
|
||||
↓
|
||||
Wait for 4+ Storage Service Responses
|
||||
↓
|
||||
Response to Gateway
|
||||
```
|
||||
|
||||
#### नई वास्तुकला
|
||||
```
|
||||
API Request → Gateway → Librarian Service
|
||||
↓
|
||||
CollectionManager
|
||||
↓
|
||||
Config Service API (put/delete/getvalues)
|
||||
↓
|
||||
Cassandra Config Table (class='collections', key='user:collection')
|
||||
↓
|
||||
Config Push (to all subscribers on config-push-queue)
|
||||
↓
|
||||
All Storage Services receive config update independently
|
||||
```
|
||||
|
||||
#### परिवर्तन 7: संग्रह प्रबंधक - कॉन्फ़िगरेशन सेवा एपीआई का उपयोग करें
|
||||
**फ़ाइल:** `trustgraph-flow/trustgraph/librarian/collection_manager.py`
|
||||
|
||||
**हटाएं:**
|
||||
`LibraryTableStore` का उपयोग (पंक्तियाँ 33, 40-41)
|
||||
स्टोरेज प्रबंधन उत्पादकों का आरंभीकरण (पंक्तियाँ 86-140)
|
||||
`on_storage_response` विधि (पंक्तियाँ 400-430)
|
||||
`pending_deletions` ट्रैकिंग (पंक्तियाँ 57, 90-96, और पूरे में उपयोग)
|
||||
|
||||
**जोड़ें:**
|
||||
एपीआई कॉल के लिए कॉन्फ़िगरेशन सेवा क्लाइंट (अनुरोध/प्रतिक्रिया पैटर्न)
|
||||
|
||||
**कॉन्फ़िगरेशन क्लाइंट सेटअप:**
|
||||
```python
|
||||
# In __init__, add config request/response producers/consumers
|
||||
from trustgraph.schema.services.config import ConfigRequest, ConfigResponse
|
||||
|
||||
# Producer for config requests
|
||||
self.config_request_producer = Producer(
|
||||
client=pulsar_client,
|
||||
topic=config_request_queue,
|
||||
schema=ConfigRequest,
|
||||
)
|
||||
|
||||
# Consumer for config responses (with correlation ID)
|
||||
self.config_response_consumer = Consumer(
|
||||
taskgroup=taskgroup,
|
||||
client=pulsar_client,
|
||||
flow=None,
|
||||
topic=config_response_queue,
|
||||
subscriber=f"{id}-config",
|
||||
schema=ConfigResponse,
|
||||
handler=self.on_config_response,
|
||||
)
|
||||
|
||||
# Tracking for pending config requests
|
||||
self.pending_config_requests = {} # request_id -> asyncio.Event
|
||||
```
|
||||
|
||||
**`list_collections` को संशोधित करें (पंक्तियाँ 145-180):**
|
||||
```python
|
||||
async def list_collections(self, user, tag_filter=None, limit=None):
|
||||
"""List collections from config service"""
|
||||
# Send getvalues request to config service
|
||||
request = ConfigRequest(
|
||||
id=str(uuid.uuid4()),
|
||||
operation='getvalues',
|
||||
type='collections',
|
||||
)
|
||||
|
||||
# Send request and wait for response
|
||||
response = await self.send_config_request(request)
|
||||
|
||||
# Parse collections from response
|
||||
collections = []
|
||||
for key, value_json in response.values.items():
|
||||
if ":" in key:
|
||||
coll_user, collection = key.split(":", 1)
|
||||
if coll_user == user:
|
||||
metadata = json.loads(value_json)
|
||||
collections.append(CollectionMetadata(**metadata))
|
||||
|
||||
# Apply tag filtering in-memory (as before)
|
||||
if tag_filter:
|
||||
collections = [c for c in collections if any(tag in c.tags for tag in tag_filter)]
|
||||
|
||||
# Apply limit
|
||||
if limit:
|
||||
collections = collections[:limit]
|
||||
|
||||
return collections
|
||||
|
||||
async def send_config_request(self, request):
|
||||
"""Send config request and wait for response"""
|
||||
event = asyncio.Event()
|
||||
self.pending_config_requests[request.id] = event
|
||||
|
||||
await self.config_request_producer.send(request)
|
||||
await event.wait()
|
||||
|
||||
return self.pending_config_requests.pop(request.id + "_response")
|
||||
|
||||
async def on_config_response(self, message, consumer, flow):
|
||||
"""Handle config response"""
|
||||
response = message.value()
|
||||
if response.id in self.pending_config_requests:
|
||||
self.pending_config_requests[response.id + "_response"] = response
|
||||
self.pending_config_requests[response.id].set()
|
||||
```
|
||||
|
||||
**`update_collection` को संशोधित करें (पंक्तियाँ 182-312):**
|
||||
```python
|
||||
async def update_collection(self, user, collection, name, description, tags):
|
||||
"""Update collection via config service"""
|
||||
# Create metadata
|
||||
metadata = CollectionMetadata(
|
||||
user=user,
|
||||
collection=collection,
|
||||
name=name,
|
||||
description=description,
|
||||
tags=tags,
|
||||
)
|
||||
|
||||
# Send put request to config service
|
||||
request = ConfigRequest(
|
||||
id=str(uuid.uuid4()),
|
||||
operation='put',
|
||||
type='collections',
|
||||
key=f'{user}:{collection}',
|
||||
value=json.dumps(metadata.to_dict()),
|
||||
)
|
||||
|
||||
response = await self.send_config_request(request)
|
||||
|
||||
if response.error:
|
||||
raise RuntimeError(f"Config update failed: {response.error.message}")
|
||||
|
||||
# Config service will trigger config push automatically
|
||||
# Storage services will receive update and create collections
|
||||
```
|
||||
|
||||
**`delete_collection` में संशोधन करें (पंक्तियाँ 314-398):**
|
||||
```python
|
||||
async def delete_collection(self, user, collection):
|
||||
"""Delete collection via config service"""
|
||||
# Send delete request to config service
|
||||
request = ConfigRequest(
|
||||
id=str(uuid.uuid4()),
|
||||
operation='delete',
|
||||
type='collections',
|
||||
key=f'{user}:{collection}',
|
||||
)
|
||||
|
||||
response = await self.send_config_request(request)
|
||||
|
||||
if response.error:
|
||||
raise RuntimeError(f"Config delete failed: {response.error.message}")
|
||||
|
||||
# Config service will trigger config push automatically
|
||||
# Storage services will receive update and delete collections
|
||||
```
|
||||
|
||||
**संग्रह मेटाडेटा प्रारूप:**
|
||||
कॉन्फ़िगरेशन तालिका में इस प्रकार संग्रहीत: `class='collections', key='user:collection'`
|
||||
मान JSON-सीरियलाइज़्ड CollectionMetadata है (समय-मुद्रांकन फ़ील्ड के बिना)
|
||||
फ़ील्ड: `user`, `collection`, `name`, `description`, `tags`
|
||||
उदाहरण: `class='collections', key='alice:my-docs', value='{"user":"alice","collection":"my-docs","name":"My Documents","description":"...","tags":["work"]}'`
|
||||
|
||||
#### परिवर्तन 8: लाइब्रेरियन सेवा - स्टोरेज मैनेजमेंट इंफ्रास्ट्रक्चर को हटाएं
|
||||
**फ़ाइल:** `trustgraph-flow/trustgraph/librarian/service.py`
|
||||
|
||||
**हटाएं:**
|
||||
स्टोरेज मैनेजमेंट प्रोड्यूसर (पंक्ति 173-190):
|
||||
`vector_storage_management_producer`
|
||||
`object_storage_management_producer`
|
||||
`triples_storage_management_producer`
|
||||
स्टोरेज रिस्पांस कंज्यूमर (पंक्ति 192-201)
|
||||
`on_storage_response` हैंडलर (पंक्ति 467-473)
|
||||
|
||||
**संशोधित करें:**
|
||||
CollectionManager इनिशियलाइज़ेशन (पंक्ति 215-224) - स्टोरेज प्रोड्यूसर पैरामीटर हटाएं
|
||||
|
||||
**ध्यान दें:** बाहरी संग्रह एपीआई अपरिवर्तित रहता है:
|
||||
`list-collections`
|
||||
`update-collection`
|
||||
`delete-collection`
|
||||
|
||||
#### परिवर्तन 9: LibraryTableStore से Collections टेबल को हटाएं
|
||||
**फ़ाइल:** `trustgraph-flow/trustgraph/tables/library.py`
|
||||
|
||||
**हटाएं:**
|
||||
Collections टेबल CREATE स्टेटमेंट (पंक्ति 114-127)
|
||||
Collections तैयार स्टेटमेंट (पंक्ति 205-240)
|
||||
सभी संग्रह विधियाँ (पंक्ति 578-717):
|
||||
`ensure_collection_exists`
|
||||
`list_collections`
|
||||
`update_collection`
|
||||
`delete_collection`
|
||||
`get_collection`
|
||||
`create_collection`
|
||||
|
||||
**तर्क:**
|
||||
संग्रह अब कॉन्फ़िगरेशन तालिका में संग्रहीत हैं।
|
||||
परिवर्तन स्वीकार्य है - डेटा माइग्रेशन की आवश्यकता नहीं है।
|
||||
लाइब्रेरियन सेवा को काफी सरल बनाता है।
|
||||
|
||||
#### परिवर्तन 10: स्टोरेज सेवाएं - कॉन्फ़िगरेशन-आधारित संग्रह प्रबंधन ✅ पूर्ण
|
||||
|
||||
**स्थिति:** सभी 11 स्टोरेज बैकएंड को `CollectionConfigHandler` का उपयोग करने के लिए माइग्रेट किया गया है।
|
||||
|
||||
**प्रभावित सेवाएं (कुल 11):**
|
||||
दस्तावेज़ एम्बेडिंग: मिलवस, पाइनकोन, क्यूड्रांट
|
||||
ग्राफ एम्बेडिंग: मिलवस, पाइनकोन, क्यूड्रांट
|
||||
ऑब्जेक्ट स्टोरेज: कैसेंड्रा
|
||||
ट्रिपल स्टोरेज: कैसेंड्रा, फाल्कोडीबी, मेमग्राफ, नियो4जे
|
||||
|
||||
**फाइलें:**
|
||||
`trustgraph-flow/trustgraph/storage/doc_embeddings/milvus/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/doc_embeddings/pinecone/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/doc_embeddings/qdrant/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/graph_embeddings/milvus/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/graph_embeddings/pinecone/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/graph_embeddings/qdrant/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/objects/cassandra/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/triples/falkordb/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/triples/memgraph/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/triples/neo4j/write.py`
|
||||
|
||||
**कार्यान्वयन पैटर्न (सभी सेवाएं):**
|
||||
|
||||
1. **`__init__` में कॉन्फ़िगरेशन हैंडलर पंजीकृत करें:**
|
||||
```python
|
||||
# Add after AsyncProcessor initialization
|
||||
self.register_config_handler(self.on_collection_config)
|
||||
self.known_collections = set() # Track (user, collection) tuples
|
||||
```
|
||||
|
||||
2. **कॉन्फ़िगरेशन हैंडलर को लागू करें:**
|
||||
```python
|
||||
async def on_collection_config(self, config, version):
|
||||
"""Handle collection configuration updates"""
|
||||
logger.info(f"Collection config version: {version}")
|
||||
|
||||
if "collections" not in config:
|
||||
return
|
||||
|
||||
# Parse collections from config
|
||||
# Key format: "user:collection" in config["collections"]
|
||||
config_collections = set()
|
||||
for key in config["collections"].keys():
|
||||
if ":" in key:
|
||||
user, collection = key.split(":", 1)
|
||||
config_collections.add((user, collection))
|
||||
|
||||
# Determine changes
|
||||
to_create = config_collections - self.known_collections
|
||||
to_delete = self.known_collections - config_collections
|
||||
|
||||
# Create new collections (idempotent)
|
||||
for user, collection in to_create:
|
||||
try:
|
||||
await self.create_collection_internal(user, collection)
|
||||
self.known_collections.add((user, collection))
|
||||
logger.info(f"Created collection: {user}/{collection}")
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to create {user}/{collection}: {e}")
|
||||
|
||||
# Delete removed collections (idempotent)
|
||||
for user, collection in to_delete:
|
||||
try:
|
||||
await self.delete_collection_internal(user, collection)
|
||||
self.known_collections.discard((user, collection))
|
||||
logger.info(f"Deleted collection: {user}/{collection}")
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to delete {user}/{collection}: {e}")
|
||||
```
|
||||
|
||||
3. **प्रारंभ में ज्ञात संग्रहों को आरंभीकृत करें:**
|
||||
```python
|
||||
async def start(self):
|
||||
"""Start the processor"""
|
||||
await super().start()
|
||||
await self.sync_known_collections()
|
||||
|
||||
async def sync_known_collections(self):
|
||||
"""Query backend to populate known_collections set"""
|
||||
# Backend-specific implementation:
|
||||
# - Milvus/Pinecone/Qdrant: List collections/indexes matching naming pattern
|
||||
# - Cassandra: Query keyspaces or collection metadata
|
||||
# - Neo4j/Memgraph/FalkorDB: Query CollectionMetadata nodes
|
||||
pass
|
||||
```
|
||||
|
||||
4. **मौजूदा हैंडलर विधियों को पुनर्गठित करें:**
|
||||
```python
|
||||
# Rename and remove response sending:
|
||||
# handle_create_collection → create_collection_internal
|
||||
# handle_delete_collection → delete_collection_internal
|
||||
|
||||
async def create_collection_internal(self, user, collection):
|
||||
"""Create collection (idempotent)"""
|
||||
# Same logic as current handle_create_collection
|
||||
# But remove response producer calls
|
||||
# Handle "already exists" gracefully
|
||||
pass
|
||||
|
||||
async def delete_collection_internal(self, user, collection):
|
||||
"""Delete collection (idempotent)"""
|
||||
# Same logic as current handle_delete_collection
|
||||
# But remove response producer calls
|
||||
# Handle "not found" gracefully
|
||||
pass
|
||||
```
|
||||
|
||||
5. **भंडारण प्रबंधन अवसंरचना को हटाएं:**
|
||||
`self.storage_request_consumer` सेटअप और प्रारंभ को हटाएं
|
||||
`self.storage_response_producer` सेटअप को हटाएं
|
||||
`on_storage_management` डिस्पैचर विधि को हटाएं
|
||||
भंडारण प्रबंधन के लिए मेट्रिक्स को हटाएं
|
||||
इम्पोर्ट को हटाएं: `StorageManagementRequest`, `StorageManagementResponse`
|
||||
|
||||
**बैकएंड-विशिष्ट विचार:**
|
||||
|
||||
**वेक्टर स्टोर (मिलवस, पाइनकोन, क्यूड्रांट):** `known_collections` में लॉजिकल `(user, collection)` को ट्रैक करें, लेकिन प्रत्येक आयाम के लिए कई बैकएंड संग्रह बनाए जा सकते हैं। आलसी निर्माण पैटर्न जारी रखें। हटाने के कार्यों को सभी आयाम वेरिएंट को हटाना चाहिए।
|
||||
|
||||
**कैसेंड्रा ऑब्जेक्ट्स:** संग्रह पंक्ति गुण हैं, संरचनाएं नहीं। कीस्पेस-स्तरीय जानकारी को ट्रैक करें।
|
||||
|
||||
**ग्राफ स्टोर (नियो4जे, मेमग्राफ, फाल्कोर्डबी):** स्टार्टअप पर `CollectionMetadata` नोड्स को क्वेरी करें। सिंक पर मेटाडेटा नोड्स बनाएं/हटाएं।
|
||||
|
||||
**कैसेंड्रा ट्रिपल्स:** संग्रह संचालन के लिए `KnowledgeGraph` एपीआई का उपयोग करें।
|
||||
|
||||
**मुख्य डिज़ाइन बिंदु:**
|
||||
|
||||
**अंतिम स्थिरता:** कोई अनुरोध/प्रतिक्रिया तंत्र नहीं, कॉन्फ़िगरेशन पुश प्रसारित किया जाता है
|
||||
**अपरिवर्तनीयता:** सभी निर्माण/हटाने के संचालन को पुनः प्रयास करना सुरक्षित होना चाहिए
|
||||
**त्रुटि प्रबंधन:** त्रुटियों को लॉग करें लेकिन कॉन्फ़िगरेशन अपडेट को अवरुद्ध न करें
|
||||
**स्व-सुधार:** विफल संचालन अगले कॉन्फ़िगरेशन पुश पर पुनः प्रयास करेंगे
|
||||
**संग्रह कुंजी प्रारूप:** `config["collections"]` में `"user:collection"`
|
||||
|
||||
#### परिवर्तन 11: संग्रह स्कीमा अपडेट करें - टाइमस्टैम्प हटाएं
|
||||
**फ़ाइल:** `trustgraph-base/trustgraph/schema/services/collection.py`
|
||||
|
||||
**संग्रहMetadata (पंक्ति 13-21) को संशोधित करें:**
|
||||
`created_at` और `updated_at` फ़ील्ड को हटाएं:
|
||||
```python
|
||||
class CollectionMetadata(Record):
|
||||
user = String()
|
||||
collection = String()
|
||||
name = String()
|
||||
description = String()
|
||||
tags = Array(String())
|
||||
# Remove: created_at = String()
|
||||
# Remove: updated_at = String()
|
||||
```
|
||||
|
||||
**कलेक्शनमैनेजमेंट रिक्वेस्ट में बदलाव (पंक्ति 25-47):**
|
||||
टाइमस्टैम्प फ़ील्ड हटाएं:
|
||||
```python
|
||||
class CollectionManagementRequest(Record):
|
||||
operation = String()
|
||||
user = String()
|
||||
collection = String()
|
||||
timestamp = String()
|
||||
name = String()
|
||||
description = String()
|
||||
tags = Array(String())
|
||||
# Remove: created_at = String()
|
||||
# Remove: updated_at = String()
|
||||
tag_filter = Array(String())
|
||||
limit = Integer()
|
||||
```
|
||||
|
||||
**तर्क:**
|
||||
टाइमस्टैम्प संग्रह के लिए कोई मूल्य नहीं जोड़ते हैं।
|
||||
कॉन्फ़िगरेशन सेवा अपनी संस्करण ट्रैकिंग बनाए रखती है।
|
||||
स्कीमा को सरल बनाता है और भंडारण को कम करता है।
|
||||
|
||||
#### कॉन्फ़िगरेशन सेवा माइग्रेशन के लाभ
|
||||
|
||||
1. ✅ **हार्डकोडेड स्टोरेज प्रबंधन विषयों को समाप्त करता है** - मल्टी-टेनेंट अवरोध को हल करता है।
|
||||
2. ✅ **सरल समन्वय** - 4+ स्टोरेज प्रतिक्रियाओं के लिए कोई जटिल एसिंक्रोनस प्रतीक्षा नहीं।
|
||||
3. ✅ **अंतिम स्थिरता** - स्टोरेज सेवाएं कॉन्फ़िगरेशन पुश के माध्यम से स्वतंत्र रूप से अपडेट करती हैं।
|
||||
4. ✅ **बेहतर विश्वसनीयता** - गैर-स्थायी अनुरोध/प्रतिक्रिया के विपरीत, लगातार कॉन्फ़िगरेशन पुश।
|
||||
5. ✅ **एकीकृत कॉन्फ़िगरेशन मॉडल** - संग्रह को कॉन्फ़िगरेशन के रूप में माना जाता है।
|
||||
6. ✅ **जटिलता को कम करता है** - ~300 लाइनों के समन्वय कोड को हटाता है।
|
||||
7. ✅ **मल्टी-टेनेंट के लिए तैयार** - कॉन्फ़िगरेशन पहले से ही कीस्पेस के माध्यम से किरायेदार अलगाव का समर्थन करता है।
|
||||
8. ✅ **संस्करण ट्रैकिंग** - कॉन्फ़िगरेशन सेवा संस्करण तंत्र ऑडिट ट्रेल प्रदान करता है।
|
||||
|
||||
## कार्यान्वयन नोट्स
|
||||
|
||||
### पिछड़ा संगतता
|
||||
|
||||
**पैरामीटर परिवर्तन:**
|
||||
CLI पैरामीटर का नाम बदलना एक ब्रेकिंग परिवर्तन है लेकिन स्वीकार्य है (फ़ीचर वर्तमान में गैर-कार्यात्मक है)।
|
||||
सेवाएं पैरामीटर के बिना काम करती हैं (डिफ़ॉल्ट का उपयोग करें)।
|
||||
डिफ़ॉल्ट कीस्पेस संरक्षित हैं: "config", "knowledge", "librarian"
|
||||
डिफ़ॉल्ट कतार: `persistent://tg/config/config`
|
||||
|
||||
**संग्रह प्रबंधन:**
|
||||
**ब्रेकिंग परिवर्तन:** लाइब्रेरियन कीस्पेस से संग्रह तालिका हटा दी गई है।
|
||||
**कोई डेटा माइग्रेशन प्रदान नहीं किया गया है** - इस चरण के लिए स्वीकार्य है।
|
||||
बाहरी संग्रह API अपरिवर्तित है (सूची/अपडेट/हटाने के संचालन)।
|
||||
संग्रह मेटाडेटा प्रारूप को सरल बनाया गया है (टाइमस्टैम्प हटा दिए गए हैं)।
|
||||
|
||||
### परीक्षण आवश्यकताएँ
|
||||
|
||||
**पैरामीटर परीक्षण:**
|
||||
1. सत्यापित करें कि `--config-push-queue` पैरामीटर ग्राफ-एम्बेडिंग सेवा पर काम करता है।
|
||||
2. सत्यापित करें कि `--config-push-queue` पैरामीटर टेक्स्ट-कंप्लीशन सेवा पर काम करता है।
|
||||
3. सत्यापित करें कि `--config-push-queue` पैरामीटर कॉन्फ़िगरेशन सेवा पर काम करता है।
|
||||
4. सत्यापित करें कि `--cassandra-keyspace` पैरामीटर कॉन्फ़िगरेशन सेवा के लिए काम करता है।
|
||||
5. सत्यापित करें कि `--cassandra-keyspace` पैरामीटर कोर सेवा के लिए काम करता है।
|
||||
6. सत्यापित करें कि `--cassandra-keyspace` पैरामीटर लाइब्रेरियन सेवा के लिए काम करता है।
|
||||
7. सत्यापित करें कि सेवाएं पैरामीटर के बिना काम करती हैं (डिफ़ॉल्ट का उपयोग करती हैं)।
|
||||
8. कस्टम कतार नामों और कीस्पेस के साथ मल्टी-टेनेंट परिनियोजन सत्यापित करें।
|
||||
|
||||
**संग्रह प्रबंधन परीक्षण:**
|
||||
9. कॉन्फ़िगरेशन सेवा के माध्यम से `list-collections` ऑपरेशन सत्यापित करें।
|
||||
10. सत्यापित करें कि `update-collection` कॉन्फ़िगरेशन तालिका में बनाता/अपडेट करता है।
|
||||
11. सत्यापित करें कि `delete-collection` कॉन्फ़िगरेशन तालिका से हटाता है।
|
||||
12. सत्यापित करें कि संग्रह अपडेट पर कॉन्फ़िगरेशन पुश ट्रिगर होता है।
|
||||
13. सत्यापित करें कि कॉन्फ़िगरेशन-आधारित स्टोरेज के साथ टैग फ़िल्टरिंग काम करता है।
|
||||
14. सत्यापित करें कि संग्रह ऑपरेशन टाइमस्टैम्प फ़ील्ड के बिना काम करते हैं।
|
||||
|
||||
### मल्टी-टेनेंट परिनियोजन उदाहरण
|
||||
```bash
|
||||
# Tenant: tg-dev
|
||||
graph-embeddings \
|
||||
-p pulsar+ssl://broker:6651 \
|
||||
--pulsar-api-key <KEY> \
|
||||
--config-push-queue persistent://tg-dev/config/config
|
||||
|
||||
config-service \
|
||||
-p pulsar+ssl://broker:6651 \
|
||||
--pulsar-api-key <KEY> \
|
||||
--config-push-queue persistent://tg-dev/config/config \
|
||||
--cassandra-keyspace tg_dev_config
|
||||
```
|
||||
|
||||
## प्रभाव विश्लेषण
|
||||
|
||||
### परिवर्तन 1-2 से प्रभावित सेवाएं (CLI पैरामीटर का नाम बदलना)
|
||||
सभी सेवाएं जो AsyncProcessor या FlowProcessor से विरासत में मिली हैं:
|
||||
config-service
|
||||
cores-service
|
||||
librarian-service
|
||||
graph-embeddings
|
||||
document-embeddings
|
||||
text-completion-* (सभी प्रदाता)
|
||||
extract-* (सभी एक्सट्रैक्टर)
|
||||
query-* (सभी क्वेरी सेवाएं)
|
||||
retrieval-* (सभी RAG सेवाएं)
|
||||
storage-* (सभी स्टोरेज सेवाएं)
|
||||
और 20+ से अधिक सेवाएं
|
||||
|
||||
### परिवर्तन 3-6 से प्रभावित सेवाएं (कैसेंड्रा कीस्पेस)
|
||||
config-service
|
||||
cores-service
|
||||
librarian-service
|
||||
|
||||
### परिवर्तन 7-11 से प्रभावित सेवाएं (संग्रह प्रबंधन)
|
||||
|
||||
**तत्काल परिवर्तन:**
|
||||
librarian-service (collection_manager.py, service.py)
|
||||
tables/library.py (संग्रह तालिका को हटाना)
|
||||
schema/services/collection.py (टाइमस्टैम्प को हटाना)
|
||||
|
||||
**पूरे हुए परिवर्तन (परिवर्तन 10):** ✅
|
||||
सभी स्टोरेज सेवाएं (कुल 11) - संग्रह अपडेट के लिए कॉन्फ़िगरेशन पुश के माध्यम से `CollectionConfigHandler` में माइग्रेट किया गया
|
||||
`storage.py` से स्टोरेज प्रबंधन स्कीमा को हटाया गया
|
||||
|
||||
## भविष्य के विचार
|
||||
|
||||
### प्रति-उपयोगकर्ता कीस्पेस मॉडल
|
||||
|
||||
कुछ सेवाएं **प्रति-उपयोगकर्ता कीस्पेस** गतिशील रूप से उपयोग करती हैं, जहां प्रत्येक उपयोगकर्ता का अपना कैसेंड्रा कीस्पेस होता है:
|
||||
|
||||
**प्रति-उपयोगकर्ता कीस्पेस वाली सेवाएं:**
|
||||
1. **ट्रिपल्स क्वेरी सर्विस** (`trustgraph-flow/trustgraph/query/triples/cassandra/service.py:65`)
|
||||
`keyspace=query.user` का उपयोग करता है
|
||||
2. **ऑब्जेक्ट्स क्वेरी सर्विस** (`trustgraph-flow/trustgraph/query/objects/cassandra/service.py:479`)
|
||||
`keyspace=self.sanitize_name(user)` का उपयोग करता है
|
||||
3. **नॉलेज ग्राफ डायरेक्ट एक्सेस** (`trustgraph-flow/trustgraph/direct/cassandra_kg.py:18`)
|
||||
डिफ़ॉल्ट पैरामीटर `keyspace="trustgraph"`
|
||||
|
||||
**स्थिति:** ये इस विनिर्देश में **बदले नहीं गए** हैं।
|
||||
|
||||
**भविष्य की समीक्षा आवश्यक:**
|
||||
मूल्यांकन करें कि क्या प्रति-उपयोगकर्ता कीस्पेस मॉडल किरायेदार अलगाव के मुद्दे बनाता है
|
||||
इस पर विचार करें कि क्या मल्टी-टेनेन्ट डिप्लॉयमेंट को कीस्पेस उपसर्ग पैटर्न (जैसे, `tenant_a_user1`) की आवश्यकता है
|
||||
किरायेदारों में संभावित उपयोगकर्ता आईडी टकराव के लिए समीक्षा करें
|
||||
मूल्यांकन करें कि क्या प्रति किरायेदार एकल साझा कीस्पेस उपयोगकर्ता-आधारित पंक्ति अलगाव के साथ अधिक उपयुक्त है
|
||||
|
||||
**नोट:** यह वर्तमान मल्टी-टेनेन्ट कार्यान्वयन को अवरुद्ध नहीं करता है, लेकिन उत्पादन मल्टी-टेनेन्ट डिप्लॉयमेंट से पहले इसकी समीक्षा की जानी चाहिए।
|
||||
|
||||
## कार्यान्वयन चरण
|
||||
|
||||
### चरण 1: पैरामीटर सुधार (परिवर्तन 1-6)
|
||||
`--config-push-queue` पैरामीटर नामकरण को ठीक करें
|
||||
`--cassandra-keyspace` पैरामीटर समर्थन जोड़ें
|
||||
**परिणाम:** मल्टी-टेनेन्ट कतार और कीस्पेस कॉन्फ़िगरेशन सक्षम
|
||||
|
||||
### चरण 2: संग्रह प्रबंधन माइग्रेशन (परिवर्तन 7-9, 11)
|
||||
संग्रह स्टोरेज को कॉन्फ़िगरेशन सेवा में माइग्रेट करें
|
||||
लाइब्रेरियन से संग्रह तालिका को हटा दें
|
||||
संग्रह स्कीमा को अपडेट करें (टाइमस्टैम्प हटाएं)
|
||||
**परिणाम:** हार्डकोडेड स्टोरेज प्रबंधन विषयों को समाप्त करता है, लाइब्रेरियन को सरल बनाता है
|
||||
|
||||
### चरण 3: स्टोरेज सर्विस अपडेट (परिवर्तन 10) ✅ पूर्ण
|
||||
सभी स्टोरेज सेवाओं को `CollectionConfigHandler` के माध्यम से संग्रह के लिए कॉन्फ़िगरेशन पुश का उपयोग करने के लिए अपडेट किया गया
|
||||
स्टोरेज प्रबंधन अनुरोध/प्रतिक्रिया बुनियादी ढांचे को हटा दिया गया
|
||||
विरासत स्कीमा परिभाषाओं को हटा दिया गया
|
||||
**परिणाम:** कॉन्फ़िगरेशन-आधारित संग्रह प्रबंधन प्राप्त हुआ
|
||||
|
||||
## संदर्भ
|
||||
GitHub मुद्दा: https://github.com/trustgraph-ai/trustgraph/issues/582
|
||||
संबंधित फाइलें:
|
||||
`trustgraph-base/trustgraph/base/async_processor.py`
|
||||
`trustgraph-base/trustgraph/base/cassandra_config.py`
|
||||
`trustgraph-base/trustgraph/schema/core/topic.py`
|
||||
`trustgraph-base/trustgraph/schema/services/collection.py`
|
||||
`trustgraph-flow/trustgraph/config/service/service.py`
|
||||
`trustgraph-flow/trustgraph/cores/service.py`
|
||||
`trustgraph-flow/trustgraph/librarian/service.py`
|
||||
`trustgraph-flow/trustgraph/librarian/collection_manager.py`
|
||||
`trustgraph-flow/trustgraph/tables/library.py`
|
||||
367
docs/tech-specs/hi/neo4j-user-collection-isolation.hi.md
Normal file
367
docs/tech-specs/hi/neo4j-user-collection-isolation.hi.md
Normal file
|
|
@ -0,0 +1,367 @@
|
|||
---
|
||||
layout: default
|
||||
title: "नियो4जे उपयोगकर्ता/संग्रह अलगाव समर्थन"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# नियो4जे उपयोगकर्ता/संग्रह अलगाव समर्थन
|
||||
|
||||
> **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.
|
||||
|
||||
## समस्या विवरण
|
||||
|
||||
नियो4जे का त्रिगुट भंडारण और क्वेरी कार्यान्वयन वर्तमान में उपयोगकर्ता/संग्रह अलगाव की कमी रखता है, जो एक बहु-किरायेदारी सुरक्षा समस्या पैदा करता है। सभी त्रिगुट एक ही ग्राफ स्पेस में संग्रहीत होते हैं, बिना किसी ऐसी तंत्र के जो उपयोगकर्ताओं को अन्य उपयोगकर्ताओं के डेटा तक पहुंचने या संग्रहों को मिलाने से रोकता हो।
|
||||
|
||||
ट्रस्टग्राफ में अन्य स्टोरेज बैकएंड के विपरीत:
|
||||
**कैसेंड्रा**: प्रत्येक उपयोगकर्ता के लिए अलग-अलग कीस्पेस और प्रत्येक संग्रह के लिए टेबल का उपयोग करता है।
|
||||
**वेक्टर स्टोर** (मिलवस, क्यूड्रांट, पाइनकोन): संग्रह-विशिष्ट नेमस्पेस का उपयोग करते हैं।
|
||||
**नियो4जे**: वर्तमान में सभी डेटा को एक ही ग्राफ में साझा करता है (सुरक्षा भेद्यता)।
|
||||
|
||||
## वर्तमान आर्किटेक्चर
|
||||
|
||||
### डेटा मॉडल
|
||||
**नोड्स**: `:Node` लेबल के साथ `uri` प्रॉपर्टी, `:Literal` लेबल के साथ `value` प्रॉपर्टी।
|
||||
**रिलेशनशिप्स**: `:Rel` लेबल के साथ `uri` प्रॉपर्टी।
|
||||
**इंडेक्स**: `Node.uri`, `Literal.value`, `Rel.uri`।
|
||||
|
||||
### संदेश प्रवाह
|
||||
`Triples` संदेशों में `metadata.user` और `metadata.collection` फ़ील्ड होते हैं।
|
||||
स्टोरेज सेवा उपयोगकर्ता/संग्रह जानकारी प्राप्त करती है लेकिन इसे अनदेखा करती है।
|
||||
क्वेरी सेवा `TriplesQueryRequest` में `user` और `collection` की अपेक्षा करती है लेकिन उन्हें अनदेखा करती है।
|
||||
|
||||
### वर्तमान सुरक्षा समस्या
|
||||
```cypher
|
||||
# Any user can query any data - no isolation
|
||||
MATCH (src:Node)-[rel:Rel]->(dest:Node)
|
||||
RETURN src.uri, rel.uri, dest.uri
|
||||
```
|
||||
|
||||
## प्रस्तावित समाधान: प्रॉपर्टी-आधारित फ़िल्टरिंग (अनुशंसित)
|
||||
|
||||
### अवलोकन
|
||||
सभी नोड्स और संबंधों में `user` और `collection` प्रॉपर्टीज़ जोड़ें, और फिर सभी ऑपरेशन्स को इन प्रॉपर्टीज़ के आधार पर फ़िल्टर करें। यह दृष्टिकोण मजबूत अलगाव प्रदान करता है, जबकि क्वेरी लचीलापन और पिछड़े अनुकूलता को बनाए रखता है।
|
||||
|
||||
### डेटा मॉडल परिवर्तन
|
||||
|
||||
#### उन्नत नोड संरचना
|
||||
```cypher
|
||||
// Node entities
|
||||
CREATE (n:Node {
|
||||
uri: "http://example.com/entity1",
|
||||
user: "john_doe",
|
||||
collection: "production_v1"
|
||||
})
|
||||
|
||||
// Literal entities
|
||||
CREATE (n:Literal {
|
||||
value: "literal value",
|
||||
user: "john_doe",
|
||||
collection: "production_v1"
|
||||
})
|
||||
```
|
||||
|
||||
#### उन्नत संबंध संरचना
|
||||
```cypher
|
||||
// Relationships with user/collection properties
|
||||
CREATE (src)-[:Rel {
|
||||
uri: "http://example.com/predicate1",
|
||||
user: "john_doe",
|
||||
collection: "production_v1"
|
||||
}]->(dest)
|
||||
```
|
||||
|
||||
#### अद्यतित अनुक्रमणिकाएँ
|
||||
```cypher
|
||||
// Compound indexes for efficient filtering
|
||||
CREATE INDEX node_user_collection_uri FOR (n:Node) ON (n.user, n.collection, n.uri);
|
||||
CREATE INDEX literal_user_collection_value FOR (n:Literal) ON (n.user, n.collection, n.value);
|
||||
CREATE INDEX rel_user_collection_uri FOR ()-[r:Rel]-() ON (r.user, r.collection, r.uri);
|
||||
|
||||
// Maintain existing indexes for backwards compatibility (optional)
|
||||
CREATE INDEX Node_uri FOR (n:Node) ON (n.uri);
|
||||
CREATE INDEX Literal_value FOR (n:Literal) ON (n.value);
|
||||
CREATE INDEX Rel_uri FOR ()-[r:Rel]-() ON (r.uri);
|
||||
```
|
||||
|
||||
### कार्यान्वयन में परिवर्तन
|
||||
|
||||
#### स्टोरेज सर्विस (`write.py`)
|
||||
|
||||
**वर्तमान कोड:**
|
||||
```python
|
||||
def create_node(self, uri):
|
||||
summary = self.io.execute_query(
|
||||
"MERGE (n:Node {uri: $uri})",
|
||||
uri=uri, database_=self.db,
|
||||
).summary
|
||||
```
|
||||
|
||||
**अद्यतित कोड:**
|
||||
```python
|
||||
def create_node(self, uri, user, collection):
|
||||
summary = self.io.execute_query(
|
||||
"MERGE (n:Node {uri: $uri, user: $user, collection: $collection})",
|
||||
uri=uri, user=user, collection=collection, database_=self.db,
|
||||
).summary
|
||||
```
|
||||
|
||||
**बेहतर `store_triples` विधि:**
|
||||
```python
|
||||
async def store_triples(self, message):
|
||||
user = message.metadata.user
|
||||
collection = message.metadata.collection
|
||||
|
||||
for t in message.triples:
|
||||
self.create_node(t.s.value, user, collection)
|
||||
|
||||
if t.o.is_uri:
|
||||
self.create_node(t.o.value, user, collection)
|
||||
self.relate_node(t.s.value, t.p.value, t.o.value, user, collection)
|
||||
else:
|
||||
self.create_literal(t.o.value, user, collection)
|
||||
self.relate_literal(t.s.value, t.p.value, t.o.value, user, collection)
|
||||
```
|
||||
|
||||
#### क्वेरी सर्विस (`service.py`)
|
||||
|
||||
**वर्तमान कोड:**
|
||||
```python
|
||||
records, summary, keys = self.io.execute_query(
|
||||
"MATCH (src:Node {uri: $src})-[rel:Rel {uri: $rel}]->(dest:Node) "
|
||||
"RETURN dest.uri as dest",
|
||||
src=query.s.value, rel=query.p.value, database_=self.db,
|
||||
)
|
||||
```
|
||||
|
||||
**अद्यतित कोड:**
|
||||
```python
|
||||
records, summary, keys = self.io.execute_query(
|
||||
"MATCH (src:Node {uri: $src, user: $user, collection: $collection})-"
|
||||
"[rel:Rel {uri: $rel, user: $user, collection: $collection}]->"
|
||||
"(dest:Node {user: $user, collection: $collection}) "
|
||||
"RETURN dest.uri as dest",
|
||||
src=query.s.value, rel=query.p.value,
|
||||
user=query.user, collection=query.collection,
|
||||
database_=self.db,
|
||||
)
|
||||
```
|
||||
|
||||
### माइग्रेशन रणनीति
|
||||
|
||||
#### चरण 1: नए डेटा में गुण जोड़ें
|
||||
1. स्टोरेज सर्विस को अपडेट करें ताकि नए त्रिगुणों में उपयोगकर्ता/संग्रह गुण जोड़े जा सकें।
|
||||
2. पिछली अनुकूलता बनाए रखें, क्योंकि प्रश्नों में गुणों की आवश्यकता नहीं होगी।
|
||||
3. मौजूदा डेटा सुलभ रहेगा, लेकिन अलग नहीं होगा।
|
||||
|
||||
#### चरण 2: मौजूदा डेटा का माइग्रेशन
|
||||
```cypher
|
||||
// Migrate existing nodes (requires default user/collection assignment)
|
||||
MATCH (n:Node) WHERE n.user IS NULL
|
||||
SET n.user = 'legacy_user', n.collection = 'default_collection';
|
||||
|
||||
MATCH (n:Literal) WHERE n.user IS NULL
|
||||
SET n.user = 'legacy_user', n.collection = 'default_collection';
|
||||
|
||||
MATCH ()-[r:Rel]->() WHERE r.user IS NULL
|
||||
SET r.user = 'legacy_user', r.collection = 'default_collection';
|
||||
```
|
||||
|
||||
#### चरण 3: अलगाव को लागू करना
|
||||
1. क्वेरी सेवा को अपडेट करें ताकि उपयोगकर्ता/संग्रह फ़िल्टरिंग की आवश्यकता हो
|
||||
2. उचित उपयोगकर्ता/संग्रह संदर्भ के बिना क्वेरी को अस्वीकार करने के लिए सत्यापन जोड़ें
|
||||
3. पुराने डेटा एक्सेस पथ को हटा दें
|
||||
|
||||
### सुरक्षा संबंधी विचार
|
||||
|
||||
#### क्वेरी सत्यापन
|
||||
```python
|
||||
async def query_triples(self, query):
|
||||
# Validate user/collection parameters
|
||||
if not query.user or not query.collection:
|
||||
raise ValueError("User and collection must be specified")
|
||||
|
||||
# All queries must include user/collection filters
|
||||
# ... rest of implementation
|
||||
```
|
||||
|
||||
#### पैरामीटर इंजेक्शन को रोकना
|
||||
केवल पैरामीटराइज़्ड क्वेरी का उपयोग करें।
|
||||
उपयोगकर्ता/संग्रह मूल्यों को स्वीकृत पैटर्न के विरुद्ध मान्य करें।
|
||||
Neo4j प्रॉपर्टी नाम आवश्यकताओं के लिए सैनिटाइजेशन पर विचार करें।
|
||||
|
||||
#### ऑडिट ट्रेल
|
||||
```python
|
||||
logger.info(f"Query executed - User: {query.user}, Collection: {query.collection}, "
|
||||
f"Pattern: {query.s}/{query.p}/{query.o}")
|
||||
```
|
||||
|
||||
## वैकल्पिक दृष्टिकोणों पर विचार
|
||||
|
||||
### विकल्प 2: लेबल-आधारित अलगाव
|
||||
|
||||
**दृष्टिकोण**: गतिशील लेबल का उपयोग करें जैसे `User_john_Collection_prod`
|
||||
|
||||
**लाभ:**
|
||||
लेबल फ़िल्टरिंग के माध्यम से मजबूत अलगाव
|
||||
लेबल इंडेक्स के साथ कुशल क्वेरी प्रदर्शन
|
||||
स्पष्ट डेटा पृथक्करण
|
||||
|
||||
**नुकसान:**
|
||||
Neo4j में लेबल की संख्या पर व्यावहारिक सीमाएं हैं (~1000)
|
||||
जटिल लेबल नाम पीढ़ी और सैनिटाइजेशन
|
||||
जब आवश्यक हो तो संग्रहों में क्वेरी करना मुश्किल होता है
|
||||
|
||||
**कार्यान्वयन उदाहरण:**
|
||||
```cypher
|
||||
CREATE (n:Node:User_john_Collection_prod {uri: "http://example.com/entity"})
|
||||
MATCH (n:User_john_Collection_prod) WHERE n:Node RETURN n
|
||||
```
|
||||
|
||||
### विकल्प 3: प्रति-उपयोगकर्ता डेटाबेस
|
||||
|
||||
**दृष्टिकोण**: प्रत्येक उपयोगकर्ता या उपयोगकर्ता/संग्रह संयोजन के लिए अलग-अलग Neo4j डेटाबेस बनाएं।
|
||||
|
||||
**लाभ:**
|
||||
पूर्ण डेटा अलगाव
|
||||
क्रॉस-संदूषण का कोई जोखिम नहीं
|
||||
प्रति-उपयोगकर्ता स्वतंत्र स्केलिंग
|
||||
|
||||
**नुकसान:**
|
||||
संसाधन ओवरहेड (प्रत्येक डेटाबेस मेमोरी का उपयोग करता है)
|
||||
जटिल डेटाबेस जीवनचक्र प्रबंधन
|
||||
Neo4j कम्युनिटी एडिशन डेटाबेस सीमाएं
|
||||
उपयोगकर्ताओं के बीच विश्लेषण करना मुश्किल
|
||||
|
||||
### विकल्प 4: समग्र कुंजी रणनीति
|
||||
|
||||
**दृष्टिकोण**: सभी URIs और मानों को उपयोगकर्ता/संग्रह जानकारी के साथ उपसर्ग करें।
|
||||
|
||||
**लाभ:**
|
||||
मौजूदा प्रश्नों के साथ संगत
|
||||
सरल कार्यान्वयन
|
||||
कोई स्कीमा परिवर्तन आवश्यक नहीं
|
||||
|
||||
**नुकसान:**
|
||||
URI प्रदूषण डेटा अर्थशास्त्र को प्रभावित करता है
|
||||
कम कुशल प्रश्न (स्ट्रिंग उपसर्ग मिलान)
|
||||
RDF/सिमेंटिक वेब मानकों का उल्लंघन
|
||||
|
||||
**कार्यान्वयन उदाहरण:**
|
||||
```python
|
||||
def make_composite_uri(uri, user, collection):
|
||||
return f"usr:{user}:col:{collection}:uri:{uri}"
|
||||
```
|
||||
|
||||
## कार्यान्वयन योजना
|
||||
|
||||
### चरण 1: आधार (सप्ताह 1)
|
||||
1. [ ] स्टोरेज सेवा को उपयोगकर्ता/संग्रह गुणों को स्वीकार करने और संग्रहीत करने के लिए अपडेट करें।
|
||||
2. [ ] कुशल क्वेरी के लिए कंपाउंड इंडेक्स जोड़ें।
|
||||
3. [ ] पिछड़े अनुकूलता परत लागू करें।
|
||||
4. [ ] नई कार्यक्षमता के लिए यूनिट परीक्षण बनाएं।
|
||||
|
||||
### चरण 2: क्वेरी अपडेट (सप्ताह 2)
|
||||
1. [ ] सभी क्वेरी पैटर्न को उपयोगकर्ता/संग्रह फ़िल्टर शामिल करने के लिए अपडेट करें।
|
||||
2. [ ] क्वेरी सत्यापन और सुरक्षा जांच जोड़ें।
|
||||
3. [ ] एकीकरण परीक्षण अपडेट करें।
|
||||
4. [ ] फ़िल्टर किए गए प्रश्नों के साथ प्रदर्शन परीक्षण।
|
||||
|
||||
### चरण 3: माइग्रेशन और परिनियोजन (सप्ताह 3)
|
||||
1. [ ] मौजूदा Neo4j उदाहरणों के लिए डेटा माइग्रेशन स्क्रिप्ट बनाएं।
|
||||
2. [ ] परिनियोजन दस्तावेज़ और रनबुक।
|
||||
3. [ ] अलगाव उल्लंघनों के लिए निगरानी और अलर्ट।
|
||||
4. [ ] कई उपयोगकर्ताओं/संग्रहों के साथ एंड-टू-एंड परीक्षण।
|
||||
|
||||
### चरण 4: मजबूती (सप्ताह 4)
|
||||
1. [ ] विरासत अनुकूलता मोड हटाएं।
|
||||
2. [ ] व्यापक ऑडिट लॉगिंग जोड़ें।
|
||||
3. [ ] सुरक्षा समीक्षा और प्रवेश परीक्षण।
|
||||
4. [ ] प्रदर्शन अनुकूलन।
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
### यूनिट परीक्षण
|
||||
```python
|
||||
def test_user_collection_isolation():
|
||||
# Store triples for user1/collection1
|
||||
processor.store_triples(triples_user1_coll1)
|
||||
|
||||
# Store triples for user2/collection2
|
||||
processor.store_triples(triples_user2_coll2)
|
||||
|
||||
# Query as user1 should only return user1's data
|
||||
results = processor.query_triples(query_user1_coll1)
|
||||
assert all_results_belong_to_user1_coll1(results)
|
||||
|
||||
# Query as user2 should only return user2's data
|
||||
results = processor.query_triples(query_user2_coll2)
|
||||
assert all_results_belong_to_user2_coll2(results)
|
||||
```
|
||||
|
||||
### एकीकरण परीक्षण (एकीकरण परीक्षण)
|
||||
मल्टी-यूजर परिदृश्य जिसमें ओवरलैपिंग डेटा शामिल है
|
||||
क्रॉस-कलेक्शन क्वेरी (विफल होनी चाहिए)
|
||||
मौजूदा डेटा के साथ माइग्रेशन परीक्षण
|
||||
बड़े डेटासेट के साथ प्रदर्शन बेंचमार्क
|
||||
|
||||
### सुरक्षा परीक्षण (सुरक्षा परीक्षण)
|
||||
अन्य उपयोगकर्ताओं के डेटा को क्वेरी करने का प्रयास
|
||||
उपयोगकर्ता/कलेक्शन पैरामीटर पर SQL इंजेक्शन-शैली के हमले
|
||||
विभिन्न क्वेरी पैटर्न के तहत पूर्ण अलगाव को सत्यापित करें
|
||||
|
||||
## प्रदर्शन संबंधी विचार (प्रदर्शन संबंधी विचार)
|
||||
|
||||
### इंडेक्स रणनीति (इंडेक्स रणनीति)
|
||||
इष्टतम फ़िल्टरिंग के लिए `(user, collection, uri)` पर कंपाउंड इंडेक्स
|
||||
यदि कुछ संग्रह बहुत बड़े हैं तो आंशिक इंडेक्स पर विचार करें
|
||||
इंडेक्स उपयोग और क्वेरी प्रदर्शन की निगरानी करें
|
||||
|
||||
### क्वेरी अनुकूलन (क्वेरी अनुकूलन)
|
||||
फ़िल्टर किए गए क्वेरी में इंडेक्स उपयोग को सत्यापित करने के लिए EXPLAIN का उपयोग करें
|
||||
बार-बार एक्सेस किए जाने वाले डेटा के लिए क्वेरी परिणाम कैशिंग पर विचार करें
|
||||
बड़ी संख्या में उपयोगकर्ताओं/संग्रहों के साथ मेमोरी उपयोग को प्रोफाइल करें
|
||||
|
||||
### मापनीयता (मापनीयता)
|
||||
प्रत्येक उपयोगकर्ता/संग्रह संयोजन अलग-अलग डेटा द्वीप बनाता है
|
||||
डेटाबेस आकार और कनेक्शन पूल उपयोग की निगरानी करें
|
||||
यदि आवश्यक हो तो क्षैतिज स्केलिंग रणनीतियों पर विचार करें
|
||||
|
||||
## सुरक्षा और अनुपालन (सुरक्षा और अनुपालन)
|
||||
|
||||
### डेटा अलगाव गारंटी (डेटा अलगाव गारंटी)
|
||||
**भौतिक**: सभी उपयोगकर्ता डेटा स्पष्ट उपयोगकर्ता/संग्रह गुणों के साथ संग्रहीत होते हैं
|
||||
**तार्किक**: सभी क्वेरी उपयोगकर्ता/संग्रह संदर्भ द्वारा फ़िल्टर की जाती हैं
|
||||
**पहुंच नियंत्रण**: सेवा-स्तरीय सत्यापन अनधिकृत पहुंच को रोकता है
|
||||
|
||||
### ऑडिट आवश्यकताएँ (ऑडिट आवश्यकताएँ)
|
||||
उपयोगकर्ता/संग्रह संदर्भ के साथ सभी डेटा एक्सेस को लॉग करें
|
||||
माइग्रेशन गतिविधियों और डेटा मूवमेंट को ट्रैक करें
|
||||
अलगाव उल्लंघन के प्रयासों की निगरानी करें
|
||||
|
||||
### अनुपालन संबंधी विचार (अनुपालन संबंधी विचार)
|
||||
जीडीपीआर: उपयोगकर्ता-विशिष्ट डेटा को खोजने और हटाने की बेहतर क्षमता
|
||||
एसओसी2: स्पष्ट डेटा अलगाव और पहुंच नियंत्रण
|
||||
एचआईपीएए: स्वास्थ्य सेवा डेटा के लिए मजबूत किरायेदार अलगाव
|
||||
|
||||
## जोखिम और निवारण (जोखिम और निवारण)
|
||||
|
||||
| जोखिम | प्रभाव | संभावना | निवारण |
|
||||
|------|--------|------------|------------|
|
||||
| क्वेरी में उपयोगकर्ता/संग्रह फ़िल्टर गुम है | उच्च | मध्यम | अनिवार्य सत्यापन, व्यापक परीक्षण
|
||||
| प्रदर्शन में गिरावट | मध्यम | कम | इंडेक्स अनुकूलन, क्वेरी प्रोफाइलिंग
|
||||
| माइग्रेशन डेटा भ्रष्टाचार | उच्च | कम | बैकअप रणनीति, रोलबैक प्रक्रियाएं
|
||||
| जटिल मल्टी-कलेक्शन क्वेरी | मध्यम | मध्यम | क्वेरी पैटर्न को दस्तावेज़ करें, उदाहरण प्रदान करें
|
||||
|
||||
## सफलता मानदंड (सफलता मानदंड)
|
||||
|
||||
1. **सुरक्षा**: उत्पादन में क्रॉस-यूजर डेटा एक्सेस शून्य
|
||||
2. **प्रदर्शन**: अनफ़िल्टर किए गए क्वेरी की तुलना में <10% क्वेरी प्रदर्शन प्रभाव
|
||||
3. **माइग्रेशन**: 100% मौजूदा डेटा बिना किसी नुकसान के सफलतापूर्वक माइग्रेट किया गया
|
||||
4. **उपयोगिता**: सभी मौजूदा क्वेरी पैटर्न उपयोगकर्ता/संग्रह संदर्भ के साथ काम करते हैं
|
||||
5. **अनुपालन**: उपयोगकर्ता/संग्रह डेटा एक्सेस का पूर्ण ऑडिट ट्रेल
|
||||
|
||||
## निष्कर्ष (निष्कर्ष)
|
||||
|
||||
संपत्ति-आधारित फ़िल्टरिंग दृष्टिकोण उपयोगकर्ता/संग्रह अलगाव को Neo4j में जोड़ने के लिए सुरक्षा, प्रदर्शन और रखरखाव के बीच सबसे अच्छा संतुलन प्रदान करता है। यह Neo4j की ग्राफ क्वेरी और इंडेक्सिंग में ताकत का लाभ उठाते हुए TrustGraph के मौजूदा मल्टी-टेनेंसी पैटर्न के साथ संरेखित है।
|
||||
|
||||
यह समाधान सुनिश्चित करता है कि TrustGraph का Neo4j बैकएंड अन्य स्टोरेज बैकएंड के समान सुरक्षा मानकों को पूरा करता है, जिससे डेटा अलगाव कमजोरियों को रोका जा सकता है, जबकि ग्राफ क्वेरी की लचीलापन और शक्ति को बनाए रखा जा सकता है।
|
||||
769
docs/tech-specs/hi/ontology-extract-phase-2.hi.md
Normal file
769
docs/tech-specs/hi/ontology-extract-phase-2.hi.md
Normal file
|
|
@ -0,0 +1,769 @@
|
|||
---
|
||||
layout: default
|
||||
title: "ऑन्टोलॉजी ज्ञान निष्कर्षण - चरण 2 का पुनर्गठन"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# ऑन्टोलॉजी ज्ञान निष्कर्षण - चरण 2 का पुनर्गठन
|
||||
|
||||
> **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.
|
||||
|
||||
**स्थिति**: मसौदा
|
||||
**लेखक**: विश्लेषण सत्र 2025-12-03
|
||||
**संबंधित**: `ontology.md`, `ontorag.md`
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह दस्तावेज़ वर्तमान ऑन्टोलॉजी-आधारित ज्ञान निष्कर्षण प्रणाली में मौजूद विसंगतियों की पहचान करता है और एलएलएम प्रदर्शन को बेहतर बनाने और सूचना हानि को कम करने के लिए एक पुनर्गठन का प्रस्ताव करता है।
|
||||
|
||||
## वर्तमान कार्यान्वयन
|
||||
|
||||
### यह वर्तमान में कैसे काम करता है
|
||||
|
||||
1. **ऑन्टोलॉजी लोडिंग** (`ontology_loader.py`)
|
||||
`"fo/Recipe"`, `"fo/Food"`, `"fo/produces"` जैसे कुंजियों के साथ ऑन्टोलॉजी JSON लोड करता है।
|
||||
क्लास आईडी में नामस्थान उपसर्ग स्वयं कुंजी में शामिल होता है।
|
||||
`food.ontology` से उदाहरण:
|
||||
```json
|
||||
"classes": {
|
||||
"fo/Recipe": {
|
||||
"uri": "http://purl.org/ontology/fo/Recipe",
|
||||
"rdfs:comment": "A Recipe is a combination..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **प्रॉम्प्ट निर्माण** (`extract.py:299-307`, `ontology-prompt.md`)
|
||||
टेम्पलेट को `classes`, `object_properties`, `datatype_properties` डिक्ट प्राप्त होते हैं।
|
||||
टेम्पलेट पुनरावृति करता है: `{% for class_id, class_def in classes.items() %}`
|
||||
एलएलएम देखता है: `**fo/Recipe**: A Recipe is a combination...`
|
||||
उदाहरण आउटपुट प्रारूप दर्शाता है:
|
||||
```json
|
||||
{"subject": "recipe:cornish-pasty", "predicate": "rdf:type", "object": "Recipe"}
|
||||
{"subject": "recipe:cornish-pasty", "predicate": "has_ingredient", "object": "ingredient:flour"}
|
||||
```
|
||||
|
||||
3. **प्रतिक्रिया पार्सिंग** (`extract.py:382-428`)
|
||||
JSON सरणी की अपेक्षा है: `[{"subject": "...", "predicate": "...", "object": "..."}]`
|
||||
यह एक उप-शब्दकोष के विरुद्ध मान्य है।
|
||||
`expand_uri()` के माध्यम से URI का विस्तार (extract.py:473-521)
|
||||
|
||||
4. **URI विस्तार** (`extract.py:473-521`)
|
||||
जांच करता है कि क्या मान `ontology_subset.classes` डिक्शनरी में है।
|
||||
यदि पाया जाता है, तो क्लास परिभाषा से URI निकालता है।
|
||||
यदि नहीं मिला, तो URI का निर्माण करता है: `f"https://trustgraph.ai/ontology/{ontology_id}#{value}"`
|
||||
|
||||
### डेटा प्रवाह उदाहरण
|
||||
|
||||
**शब्दकोष JSON → लोडर → प्रॉम्प्ट:**
|
||||
```
|
||||
"fo/Recipe" → classes["fo/Recipe"] → LLM sees "**fo/Recipe**"
|
||||
```
|
||||
|
||||
**एलएलएम → पार्सर → आउटपुट:**
|
||||
```
|
||||
"Recipe" → not in classes["fo/Recipe"] → constructs URI → LOSES original URI
|
||||
"fo/Recipe" → found in classes → uses original URI → PRESERVES URI
|
||||
```
|
||||
|
||||
## पहचाने गए मुद्दे
|
||||
|
||||
### 1. **प्रॉम्प्ट में असंगत उदाहरण**
|
||||
|
||||
**समस्या**: प्रॉम्प्ट टेम्पलेट क्लास आईडी को उपसर्गों (`fo/Recipe`) के साथ दिखाता है, लेकिन उदाहरण आउटपुट में उपसर्ग रहित क्लास नाम (`Recipe`) का उपयोग किया गया है।
|
||||
|
||||
**स्थान**: `ontology-prompt.md:5-52`
|
||||
|
||||
```markdown
|
||||
## Ontology Classes:
|
||||
- **fo/Recipe**: A Recipe is...
|
||||
|
||||
## Example Output:
|
||||
{"subject": "recipe:cornish-pasty", "predicate": "rdf:type", "object": "Recipe"}
|
||||
```
|
||||
|
||||
**प्रभाव**: एलएलएम को किस प्रारूप का उपयोग करना है, इसके बारे में विरोधाभासी संकेत प्राप्त होते हैं।
|
||||
|
||||
### 2. **यूआरआई विस्तार में सूचना का नुकसान**
|
||||
|
||||
**समस्या**: जब एलएलएम उदाहरण के बाद बिना उपसर्ग वाले क्लास नामों को लौटाता है, तो `expand_uri()` उन्हें ऑन्टोलॉजी डिक्शनरी में नहीं ढूंढ पाता है और डिफ़ॉल्ट यूआरआई बनाता है, जिससे मूल सही यूआरआई खो जाते हैं।
|
||||
|
||||
**स्थान**: `extract.py:494-500`
|
||||
|
||||
```python
|
||||
if value in ontology_subset.classes: # Looks for "Recipe"
|
||||
class_def = ontology_subset.classes[value] # But key is "fo/Recipe"
|
||||
if isinstance(class_def, dict) and 'uri' in class_def:
|
||||
return class_def['uri'] # Never reached!
|
||||
return f"https://trustgraph.ai/ontology/{ontology_id}#{value}" # Fallback
|
||||
```
|
||||
|
||||
**प्रभाव:**
|
||||
मूल यूआरआई: `http://purl.org/ontology/fo/Recipe`
|
||||
निर्मित यूआरआई: `https://trustgraph.ai/ontology/food#Recipe`
|
||||
अर्थ संबंधी जानकारी खो जाती है, इससे अंतर-क्षमता बाधित होती है।
|
||||
|
||||
### 3. **अस्पष्ट इकाई उदाहरण प्रारूप**
|
||||
|
||||
**समस्या:** इकाई उदाहरण यूआरआई प्रारूप के बारे में कोई स्पष्ट मार्गदर्शन नहीं है।
|
||||
|
||||
**प्रॉम्प्ट में उदाहरण:**
|
||||
`"recipe:cornish-pasty"` (नेमस्पेस जैसा उपसर्ग)
|
||||
`"ingredient:flour"` (एक अलग उपसर्ग)
|
||||
|
||||
**वास्तविक व्यवहार** (extract.py:517-520):
|
||||
```python
|
||||
# Treat as entity instance - construct unique URI
|
||||
normalized = value.replace(" ", "-").lower()
|
||||
return f"https://trustgraph.ai/{ontology_id}/{normalized}"
|
||||
```
|
||||
|
||||
**प्रभाव**: एलएलएम को किसी भी संदर्भ के बिना उपसर्ग सम्मेलन का अनुमान लगाना होगा।
|
||||
|
||||
### 4. **कोई नेमस्पेस उपसर्ग मार्गदर्शन नहीं**
|
||||
|
||||
**समस्या**: ऑन्टोलॉजी JSON में नेमस्पेस परिभाषाएँ हैं (food.ontology में पंक्ति 10-25):
|
||||
```json
|
||||
"namespaces": {
|
||||
"fo": "http://purl.org/ontology/fo/",
|
||||
"rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
लेकिन ये जानकारी कभी भी एलएलएम (LLM) तक नहीं पहुंचती। एलएलएम को यह नहीं पता:
|
||||
"fo" का क्या मतलब है
|
||||
एंटिटीज के लिए किस उपसर्ग का उपयोग करना है
|
||||
कौन सा नेमस्पेस किस तत्व पर लागू होता है
|
||||
|
||||
### 5. **प्रॉम्प्ट में उपयोग नहीं किए गए लेबल**
|
||||
|
||||
**समस्या**: प्रत्येक क्लास में `rdfs:label` फ़ील्ड होते हैं (उदाहरण के लिए, `{"value": "Recipe", "lang": "en-gb"}`), लेकिन प्रॉम्प्ट टेम्पलेट इनका उपयोग नहीं करता है।
|
||||
|
||||
**वर्तमान**: केवल `class_id` और `comment` दिखाता है।
|
||||
```jinja
|
||||
- **{{class_id}}**{% if class_def.comment %}: {{class_def.comment}}{% endif %}
|
||||
```
|
||||
|
||||
**उपलब्ध लेकिन अप्रयुक्त**:
|
||||
```python
|
||||
"rdfs:label": [{"value": "Recipe", "lang": "en-gb"}]
|
||||
```
|
||||
|
||||
**प्रभाव**: यह तकनीकी आईडी के साथ पठनीय नाम प्रदान कर सकता है।
|
||||
|
||||
## प्रस्तावित समाधान
|
||||
|
||||
### विकल्प ए: उपसर्ग रहित आईडी में मानकीकरण
|
||||
|
||||
**दृष्टिकोण**: एलएलएम को दिखाने से पहले क्लास आईडी से उपसर्ग हटाएं।
|
||||
|
||||
**परिवर्तन**:
|
||||
1. `build_extraction_variables()` को बदलने के लिए:
|
||||
```python
|
||||
classes_for_prompt = {
|
||||
k.split('/')[-1]: v # "fo/Recipe" → "Recipe"
|
||||
for k, v in ontology_subset.classes.items()
|
||||
}
|
||||
```
|
||||
|
||||
2. उदाहरण प्रॉम्प्ट को अपडेट करें ताकि वह मेल खाए (यह पहले से ही बिना उपसर्ग वाले नामों का उपयोग करता है)।
|
||||
|
||||
3. `expand_uri()` को दोनों प्रारूपों को संभालने के लिए संशोधित करें:
|
||||
```python
|
||||
# Try exact match first
|
||||
if value in ontology_subset.classes:
|
||||
return ontology_subset.classes[value]['uri']
|
||||
|
||||
# Try with prefix
|
||||
for prefix in ['fo/', 'rdf:', 'rdfs:']:
|
||||
prefixed = f"{prefix}{value}"
|
||||
if prefixed in ontology_subset.classes:
|
||||
return ontology_subset.classes[prefixed]['uri']
|
||||
```
|
||||
|
||||
**लाभ:**
|
||||
अधिक स्पष्ट, अधिक मानव-पठनीय
|
||||
मौजूदा प्रॉम्प्ट उदाहरणों से मेल खाता है
|
||||
एलएलएम सरल टोकन के साथ बेहतर काम करते हैं
|
||||
|
||||
**नुकसान:**
|
||||
यदि कई ऑन्टोलॉजी में समान क्लास नाम है तो क्लास नाम टकराव हो सकता है
|
||||
नेमस्पेस जानकारी खो जाती है
|
||||
लुकअप के लिए फॉलबैक लॉजिक की आवश्यकता होती है
|
||||
|
||||
### विकल्प बी: पूर्ण उपसर्ग आईडी का लगातार उपयोग करें
|
||||
|
||||
**दृष्टिकोण:** उदाहरणों को अपडेट करें ताकि वे क्लास सूची में दिखाए गए उपसर्ग आईडी से मेल खाएं।
|
||||
|
||||
**परिवर्तन:**
|
||||
1. प्रॉम्प्ट उदाहरण अपडेट करें (ontology-prompt.md:46-52):
|
||||
```json
|
||||
[
|
||||
{"subject": "recipe:cornish-pasty", "predicate": "rdf:type", "object": "fo/Recipe"},
|
||||
{"subject": "recipe:cornish-pasty", "predicate": "rdfs:label", "object": "Cornish Pasty"},
|
||||
{"subject": "recipe:cornish-pasty", "predicate": "fo/produces", "object": "food:cornish-pasty"},
|
||||
{"subject": "food:cornish-pasty", "predicate": "rdf:type", "object": "fo/Food"}
|
||||
]
|
||||
```
|
||||
|
||||
2. प्रॉम्प्ट में नेमस्पेस स्पष्टीकरण जोड़ें:
|
||||
```markdown
|
||||
## Namespace Prefixes:
|
||||
- **fo/**: Food Ontology (http://purl.org/ontology/fo/)
|
||||
- **rdf:**: RDF Schema
|
||||
- **rdfs:**: RDF Schema
|
||||
|
||||
Use these prefixes exactly as shown when referencing classes and properties.
|
||||
```
|
||||
|
||||
3. `expand_uri()` को वैसे ही रखें (जब मिलान पाया जाता है तो यह ठीक से काम करता है)।
|
||||
|
||||
**लाभ:**
|
||||
इनपुट = आउटपुट स्थिरता
|
||||
कोई जानकारी हानि नहीं
|
||||
नेमस्पेस सिमेंटिक्स को संरक्षित करता है
|
||||
कई ऑन्टोलॉजी के साथ काम करता है
|
||||
|
||||
**नुकसान:**
|
||||
एलएलएम के लिए अधिक विस्तृत टोकन
|
||||
एलएलएम को उपसर्गों को ट्रैक करने की आवश्यकता होती है
|
||||
|
||||
### विकल्प सी: हाइब्रिड - लेबल और आईडी दोनों दिखाएं
|
||||
|
||||
**दृष्टिकोण:** प्रॉम्प्ट को इस तरह से बेहतर बनाएं कि मानव-पठनीय लेबल और तकनीकी आईडी दोनों दिखाए जाएं।
|
||||
|
||||
**परिवर्तन:**
|
||||
1. प्रॉम्प्ट टेम्पलेट को अपडेट करें:
|
||||
```jinja
|
||||
{% for class_id, class_def in classes.items() %}
|
||||
- **{{class_id}}** (label: "{{class_def.labels[0].value if class_def.labels else class_id}}"){% if class_def.comment %}: {{class_def.comment}}{% endif %}
|
||||
{% endfor %}
|
||||
```
|
||||
|
||||
उदाहरण आउटपुट:
|
||||
```markdown
|
||||
- **fo/Recipe** (label: "Recipe"): A Recipe is a combination...
|
||||
```
|
||||
|
||||
2. अपडेट निर्देश:
|
||||
```markdown
|
||||
When referencing classes:
|
||||
- Use the full prefixed ID (e.g., "fo/Recipe") in JSON output
|
||||
- The label (e.g., "Recipe") is for human understanding only
|
||||
```
|
||||
|
||||
**लाभ:**
|
||||
एलएलएम (LLM) के लिए सबसे स्पष्ट।
|
||||
सभी जानकारी को संरक्षित करता है।
|
||||
यह स्पष्ट करता है कि क्या उपयोग करना है।
|
||||
|
||||
**नुकसान:**
|
||||
लंबा प्रॉम्प्ट।
|
||||
अधिक जटिल टेम्पलेट।
|
||||
|
||||
## कार्यान्वित दृष्टिकोण
|
||||
|
||||
**सरलीकृत इकाई-संबंध-विशेषता प्रारूप** - पुराने ट्रिपल-आधारित प्रारूप को पूरी तरह से बदल देता है।
|
||||
|
||||
इस नए दृष्टिकोण को इसलिए चुना गया क्योंकि:
|
||||
|
||||
1. **कोई जानकारी हानि नहीं:** मूल यूआरआई (URI) सही ढंग से संरक्षित हैं।
|
||||
2. **सरल तर्क:** किसी रूपांतरण की आवश्यकता नहीं है, सीधे डिक्ट (dict) लुकअप काम करते हैं।
|
||||
3. **नेमस्पेस सुरक्षा:** टकराव के बिना कई ऑन्टोलॉजी (ontology) को संभालता है।
|
||||
4. **सिमेंटिक (semantic) शुद्धता:** आरडीएफ/ओडब्ल्यूएल (RDF/OWL) सिमेंटिक्स को बनाए रखता है।
|
||||
|
||||
## कार्यान्वयन पूर्ण
|
||||
|
||||
### क्या बनाया गया:
|
||||
|
||||
1. **नया प्रॉम्प्ट टेम्पलेट** (`prompts/ontology-extract-v2.txt`)
|
||||
✅ स्पष्ट अनुभाग: इकाई प्रकार, संबंध, विशेषताएँ।
|
||||
✅ पूर्ण प्रकार पहचानकर्ताओं का उपयोग करके उदाहरण (`fo/Recipe`, `fo/has_ingredient`)।
|
||||
✅ स्कीमा (schema) से सटीक पहचानकर्ताओं का उपयोग करने के निर्देश।
|
||||
✅ संस्थाओं/संबंधों/विशेषताओं के सरणियों के साथ नया JSON प्रारूप।
|
||||
|
||||
2. **एंटिटी नॉर्मलाइजेशन** (`entity_normalizer.py`)
|
||||
✅ `normalize_entity_name()` - नामों को URI-सुरक्षित प्रारूप में परिवर्तित करता है
|
||||
✅ `normalize_type_identifier()` - प्रकारों में स्लैश को संभालता है (`fo/Recipe` → `fo-recipe`)
|
||||
✅ `build_entity_uri()` - (नाम, प्रकार) टपल का उपयोग करके अद्वितीय URI बनाता है
|
||||
✅ `EntityRegistry` - डुप्लिकेट से बचने के लिए एंटिटीज को ट्रैक करता है
|
||||
|
||||
3. **JSON पार्सर** (`simplified_parser.py`)
|
||||
✅ नए प्रारूप को पार्स करता है: `{entities: [...], relationships: [...], attributes: [...]}`
|
||||
✅ केबाब-केस और स्नेक_केस फ़ील्ड नामों का समर्थन करता है
|
||||
✅ संरचित डेटाक्लासेस लौटाता है
|
||||
✅ लॉगिंग के साथ त्रुटि प्रबंधन
|
||||
|
||||
4. **ट्रिपल कन्वर्टर** (`triple_converter.py`)
|
||||
✅ `convert_entity()` - स्वचालित रूप से प्रकार + लेबल त्रिक उत्पन्न करता है।
|
||||
✅ `convert_relationship()` - एंटिटी यूआरआई को गुणों के माध्यम से जोड़ता है।
|
||||
✅ `convert_attribute()` - शाब्दिक मान जोड़ता है।
|
||||
✅ ऑन्टोलॉजी परिभाषाओं से पूर्ण यूआरआई की खोज करता है।
|
||||
|
||||
5. **अपडेटेड मुख्य प्रोसेसर** (`extract.py`)
|
||||
✅ पुराने ट्रिपल-आधारित निष्कर्षण कोड को हटा दिया गया।
|
||||
✅ `extract_with_simplified_format()` विधि जोड़ी गई।
|
||||
✅ अब केवल नए सरलीकृत प्रारूप का उपयोग करता है।
|
||||
✅ `extract-with-ontologies-v2` आईडी के साथ प्रॉम्प्ट को कॉल करता है।
|
||||
|
||||
## परीक्षण मामले
|
||||
|
||||
### परीक्षण 1: यूआरआई संरक्षण
|
||||
```python
|
||||
# Given ontology class
|
||||
classes = {"fo/Recipe": {"uri": "http://purl.org/ontology/fo/Recipe", ...}}
|
||||
|
||||
# When LLM returns
|
||||
llm_output = {"subject": "x", "predicate": "rdf:type", "object": "fo/Recipe"}
|
||||
|
||||
# Then expanded URI should be
|
||||
assert expanded == "http://purl.org/ontology/fo/Recipe"
|
||||
# Not: "https://trustgraph.ai/ontology/food#Recipe"
|
||||
```
|
||||
|
||||
### परीक्षण 2: बहु-ऑन्टोलॉजी टकराव
|
||||
```python
|
||||
# Given two ontologies
|
||||
ont1 = {"fo/Recipe": {...}}
|
||||
ont2 = {"cooking/Recipe": {...}}
|
||||
|
||||
# LLM should use full prefix to disambiguate
|
||||
llm_output = {"object": "fo/Recipe"} # Not just "Recipe"
|
||||
```
|
||||
|
||||
### परीक्षण 3: इकाई उदाहरण प्रारूप
|
||||
```python
|
||||
# Given prompt with food ontology
|
||||
# LLM should create instances like
|
||||
{"subject": "recipe:cornish-pasty"} # Namespace-style
|
||||
{"subject": "food:beef"} # Consistent prefix
|
||||
```
|
||||
|
||||
## खुले प्रश्न
|
||||
|
||||
1. **क्या एंटिटी इंस्टेंस में नेमस्पेस उपसर्गों का उपयोग किया जाना चाहिए?**
|
||||
वर्तमान: `"recipe:cornish-pasty"` (यादृच्छिक)
|
||||
वैकल्पिक: क्या हमें ऑन्टोलॉजी उपसर्ग `"fo:cornish-pasty"` का उपयोग करना चाहिए?
|
||||
वैकल्पिक: कोई उपसर्ग नहीं, URI में विस्तार करें `"cornish-pasty"` → पूर्ण URI?
|
||||
|
||||
2. **प्रॉम्प्ट में डोमेन/रेंज को कैसे संभालें?**
|
||||
वर्तमान में दिखाता है: `(Recipe → Food)`
|
||||
क्या इसे `(fo/Recipe → fo/Food)` होना चाहिए?
|
||||
|
||||
3. **क्या हमें डोमेन/रेंज बाधाओं को मान्य करना चाहिए?**
|
||||
TODO टिप्पणी extract.py:470 पर
|
||||
यह अधिक त्रुटियों को पकड़ लेगा लेकिन अधिक जटिल होगा
|
||||
|
||||
4. **उलटा गुण और तुल्यता के बारे में क्या?**
|
||||
ऑन्टोलॉजी में `owl:inverseOf`, `owl:equivalentClass` है
|
||||
वर्तमान में निष्कर्षण में उपयोग नहीं किया जाता है
|
||||
क्या उन्हें उपयोग किया जाना चाहिए?
|
||||
|
||||
## सफलता मेट्रिक्स
|
||||
|
||||
✅ शून्य URI जानकारी हानि (मूल URIs का 100% संरक्षण)
|
||||
✅ LLM आउटपुट प्रारूप इनपुट प्रारूप से मेल खाता है
|
||||
✅ प्रॉम्प्ट में कोई अस्पष्ट उदाहरण नहीं
|
||||
✅ कई ऑन्टोलॉजी के साथ परीक्षण पास होते हैं
|
||||
✅ बेहतर निष्कर्षण गुणवत्ता (वैध ट्रिपल % द्वारा मापा गया)
|
||||
|
||||
## वैकल्पिक दृष्टिकोण: सरलीकृत निष्कर्षण प्रारूप
|
||||
|
||||
### दर्शन
|
||||
|
||||
LLM से RDF/OWL सिमेंटिक्स को समझने के बजाय, उससे वह कार्य करवाएं जिसमें वह अच्छा है: **पाठ में एंटिटीज और संबंधों को ढूंढना।**
|
||||
|
||||
URI निर्माण, RDF रूपांतरण और सिमेंटिक वेब औपचारिकताएं कोड द्वारा संभाली जाएं।
|
||||
|
||||
### उदाहरण: एंटिटी वर्गीकरण
|
||||
|
||||
**इनपुट टेक्स्ट:**
|
||||
```
|
||||
Cornish pasty is a traditional British pastry filled with meat and vegetables.
|
||||
```
|
||||
|
||||
**ऑन्टोलॉजी स्कीमा (एलएलएम को दिखाया गया):**
|
||||
```markdown
|
||||
## Entity Types:
|
||||
- Recipe: A recipe is a combination of ingredients and a method
|
||||
- Food: A food is something that can be eaten
|
||||
- Ingredient: An ingredient combines a quantity and a food
|
||||
```
|
||||
|
||||
**एलएलएम क्या लौटाता है (सरल JSON):**
|
||||
```json
|
||||
{
|
||||
"entities": [
|
||||
{
|
||||
"entity": "Cornish pasty",
|
||||
"type": "Recipe"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**कोड क्या उत्पन्न करता है (आरडीएफ ट्रिपल्स):**
|
||||
```python
|
||||
# 1. Normalize entity name + type to ID (type prevents collisions)
|
||||
entity_id = "recipe-cornish-pasty" # normalize("Cornish pasty", "Recipe")
|
||||
entity_uri = "https://trustgraph.ai/food/recipe-cornish-pasty"
|
||||
|
||||
# Note: Same name, different type = different URI
|
||||
# "Cornish pasty" (Recipe) → recipe-cornish-pasty
|
||||
# "Cornish pasty" (Food) → food-cornish-pasty
|
||||
|
||||
# 2. Generate triples
|
||||
triples = [
|
||||
# Type triple
|
||||
Triple(
|
||||
s=Value(value=entity_uri, is_uri=True),
|
||||
p=Value(value="http://www.w3.org/1999/02/22-rdf-syntax-ns#type", is_uri=True),
|
||||
o=Value(value="http://purl.org/ontology/fo/Recipe", is_uri=True)
|
||||
),
|
||||
# Label triple (automatic)
|
||||
Triple(
|
||||
s=Value(value=entity_uri, is_uri=True),
|
||||
p=Value(value="http://www.w3.org/2000/01/rdf-schema#label", is_uri=True),
|
||||
o=Value(value="Cornish pasty", is_uri=False)
|
||||
)
|
||||
]
|
||||
```
|
||||
|
||||
### लाभ
|
||||
|
||||
1. **एलएलएम को इसकी आवश्यकता नहीं है:**
|
||||
यूआरआई सिंटैक्स को समझना
|
||||
पहचानकर्ता उपसर्गों का आविष्कार करना (`recipe:`, `ingredient:`)
|
||||
`rdf:type` या `rdfs:label` के बारे में जानना
|
||||
सिमेंटिक वेब पहचानकर्ताओं का निर्माण करना
|
||||
|
||||
2. **एलएलएम को केवल इसकी आवश्यकता है:**
|
||||
पाठ में संस्थाओं को खोजना
|
||||
उन्हें ऑन्टोलॉजी कक्षाओं में मैप करना
|
||||
संबंधों और विशेषताओं को निकालना
|
||||
|
||||
3. **कोड द्वारा संभाला जाता है:**
|
||||
यूआरआई सामान्यीकरण और निर्माण
|
||||
आरडीएफ ट्रिपल पीढ़ी
|
||||
स्वचालित लेबल असाइनमेंट
|
||||
नेमस्पेस प्रबंधन
|
||||
|
||||
### यह बेहतर क्यों है
|
||||
|
||||
**सरल प्रॉम्प्ट** = कम भ्रम = कम त्रुटियां
|
||||
**संगत आईडी** = कोड सामान्यीकरण नियमों को नियंत्रित करता है
|
||||
**स्वचालित रूप से उत्पन्न लेबल** = कोई छूटी हुई rdfs:label ट्रिपल नहीं
|
||||
**एलएलएम निष्कर्षण पर केंद्रित है** = जो कि वास्तव में इसकी क्षमता है
|
||||
|
||||
### उदाहरण: इकाई संबंध
|
||||
|
||||
**इनपुट टेक्स्ट:**
|
||||
```
|
||||
Cornish pasty is a traditional British pastry filled with beef and potatoes.
|
||||
```
|
||||
|
||||
**ऑन्टोलॉजी स्कीमा (एलएलएम को दिखाया गया):**
|
||||
```markdown
|
||||
## Entity Types:
|
||||
- Recipe: A recipe is a combination of ingredients and a method
|
||||
- Food: A food is something that can be eaten
|
||||
- Ingredient: An ingredient combines a quantity and a food
|
||||
|
||||
## Relationships:
|
||||
- has_ingredient: Relates a recipe to an ingredient it uses (Recipe → Ingredient)
|
||||
- food: Relates an ingredient to the food that is required (Ingredient → Food)
|
||||
```
|
||||
|
||||
**एलएलएम क्या लौटाता है (सरल JSON):**
|
||||
```json
|
||||
{
|
||||
"entities": [
|
||||
{
|
||||
"entity": "Cornish pasty",
|
||||
"type": "Recipe"
|
||||
},
|
||||
{
|
||||
"entity": "beef",
|
||||
"type": "Food"
|
||||
},
|
||||
{
|
||||
"entity": "potatoes",
|
||||
"type": "Food"
|
||||
}
|
||||
],
|
||||
"relationships": [
|
||||
{
|
||||
"subject": "Cornish pasty",
|
||||
"subject-type": "Recipe",
|
||||
"relation": "has_ingredient",
|
||||
"object": "beef",
|
||||
"object-type": "Food"
|
||||
},
|
||||
{
|
||||
"subject": "Cornish pasty",
|
||||
"subject-type": "Recipe",
|
||||
"relation": "has_ingredient",
|
||||
"object": "potatoes",
|
||||
"object-type": "Food"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**कोड क्या उत्पन्न करता है (आरडीएफ ट्रिपल्स):**
|
||||
```python
|
||||
# Normalize entity names to URIs
|
||||
cornish_pasty_uri = "https://trustgraph.ai/food/cornish-pasty"
|
||||
beef_uri = "https://trustgraph.ai/food/beef"
|
||||
potatoes_uri = "https://trustgraph.ai/food/potatoes"
|
||||
|
||||
# Look up relation URI from ontology
|
||||
has_ingredient_uri = "http://purl.org/ontology/fo/ingredients" # from fo/has_ingredient
|
||||
|
||||
triples = [
|
||||
# Entity type triples (as before)
|
||||
Triple(s=cornish_pasty_uri, p=rdf_type, o="http://purl.org/ontology/fo/Recipe"),
|
||||
Triple(s=cornish_pasty_uri, p=rdfs_label, o="Cornish pasty"),
|
||||
|
||||
Triple(s=beef_uri, p=rdf_type, o="http://purl.org/ontology/fo/Food"),
|
||||
Triple(s=beef_uri, p=rdfs_label, o="beef"),
|
||||
|
||||
Triple(s=potatoes_uri, p=rdf_type, o="http://purl.org/ontology/fo/Food"),
|
||||
Triple(s=potatoes_uri, p=rdfs_label, o="potatoes"),
|
||||
|
||||
# Relationship triples
|
||||
Triple(
|
||||
s=Value(value=cornish_pasty_uri, is_uri=True),
|
||||
p=Value(value=has_ingredient_uri, is_uri=True),
|
||||
o=Value(value=beef_uri, is_uri=True)
|
||||
),
|
||||
Triple(
|
||||
s=Value(value=cornish_pasty_uri, is_uri=True),
|
||||
p=Value(value=has_ingredient_uri, is_uri=True),
|
||||
o=Value(value=potatoes_uri, is_uri=True)
|
||||
)
|
||||
]
|
||||
```
|
||||
|
||||
**मुख्य बातें:**
|
||||
एलएलएम प्राकृतिक भाषा में इकाई नामों को लौटाता है: `"Cornish pasty"`, `"beef"`, `"potatoes"`
|
||||
एलएलएम अस्पष्टता को दूर करने के लिए प्रकारों को शामिल करता है: `subject-type`, `object-type`
|
||||
एलएलएम स्कीमा से संबंध नाम का उपयोग करता है: `"has_ingredient"`
|
||||
कोड (नाम, प्रकार) का उपयोग करके सुसंगत आईडी प्राप्त करता है: `("Cornish pasty", "Recipe")` → `recipe-cornish-pasty`
|
||||
कोड ऑन्टोलॉजी से संबंध यूआरआई को देखता है: `fo/has_ingredient` → पूर्ण यूआरआई
|
||||
समान (नाम, प्रकार) टपल हमेशा समान यूआरआई प्राप्त करता है (डुप्लिकेट हटाने)।
|
||||
|
||||
### उदाहरण: इकाई नाम का अस्पष्टता निवारण
|
||||
|
||||
**समस्या:** एक ही नाम अलग-अलग इकाई प्रकारों को संदर्भित कर सकता है।
|
||||
|
||||
**वास्तविक दुनिया का मामला:**
|
||||
```
|
||||
"Cornish pasty" can be:
|
||||
- A Recipe (instructions for making it)
|
||||
- A Food (the dish itself)
|
||||
```
|
||||
|
||||
**यह कैसे संभाला जाता है:**
|
||||
|
||||
एलएलएम दोनों को अलग-अलग इकाइयों के रूप में लौटाता है:
|
||||
```json
|
||||
{
|
||||
"entities": [
|
||||
{"entity": "Cornish pasty", "type": "Recipe"},
|
||||
{"entity": "Cornish pasty", "type": "Food"}
|
||||
],
|
||||
"relationships": [
|
||||
{
|
||||
"subject": "Cornish pasty",
|
||||
"subject-type": "Recipe",
|
||||
"relation": "produces",
|
||||
"object": "Cornish pasty",
|
||||
"object-type": "Food"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**कोड समाधान:**
|
||||
```python
|
||||
# Different types → different URIs
|
||||
recipe_uri = normalize("Cornish pasty", "Recipe")
|
||||
# → "https://trustgraph.ai/food/recipe-cornish-pasty"
|
||||
|
||||
food_uri = normalize("Cornish pasty", "Food")
|
||||
# → "https://trustgraph.ai/food/food-cornish-pasty"
|
||||
|
||||
# Relationship connects them correctly
|
||||
triple = Triple(
|
||||
s=recipe_uri, # The Recipe
|
||||
p="http://purl.org/ontology/fo/produces",
|
||||
o=food_uri # The Food
|
||||
)
|
||||
```
|
||||
|
||||
**यह क्यों काम करता है:**
|
||||
प्रकार सभी संदर्भों (इकाइयों, संबंधों, विशेषताओं) में शामिल है।
|
||||
कोड `(name, type)` टपल को लुकअप कुंजी के रूप में उपयोग करता है।
|
||||
कोई अस्पष्टता नहीं, कोई टकराव नहीं।
|
||||
|
||||
### उदाहरण: इकाई विशेषताएँ
|
||||
|
||||
**इनपुट टेक्स्ट:**
|
||||
```
|
||||
This Cornish pasty recipe serves 4-6 people and takes 45 minutes to prepare.
|
||||
```
|
||||
|
||||
**ऑन्टोलॉजी स्कीमा (एलएलएम को दिखाया गया):**
|
||||
```markdown
|
||||
## Entity Types:
|
||||
- Recipe: A recipe is a combination of ingredients and a method
|
||||
|
||||
## Attributes:
|
||||
- serves: Indicates what the recipe is intended to serve (Recipe → text)
|
||||
- preparation_time: Time needed to prepare the recipe (Recipe → text)
|
||||
```
|
||||
|
||||
**एलएलएम क्या लौटाता है (सरल JSON):**
|
||||
```json
|
||||
{
|
||||
"entities": [
|
||||
{
|
||||
"entity": "Cornish pasty recipe",
|
||||
"type": "Recipe"
|
||||
}
|
||||
],
|
||||
"attributes": [
|
||||
{
|
||||
"entity": "Cornish pasty recipe",
|
||||
"entity-type": "Recipe",
|
||||
"attribute": "serves",
|
||||
"value": "4-6 people"
|
||||
},
|
||||
{
|
||||
"entity": "Cornish pasty recipe",
|
||||
"entity-type": "Recipe",
|
||||
"attribute": "preparation_time",
|
||||
"value": "45 minutes"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**कोड क्या उत्पन्न करता है (आरडीएफ ट्रिपल्स):**
|
||||
```python
|
||||
# Normalize entity name to URI
|
||||
recipe_uri = "https://trustgraph.ai/food/cornish-pasty-recipe"
|
||||
|
||||
# Look up attribute URIs from ontology
|
||||
serves_uri = "http://purl.org/ontology/fo/serves" # from fo/serves
|
||||
prep_time_uri = "http://purl.org/ontology/fo/preparation_time" # from fo/preparation_time
|
||||
|
||||
triples = [
|
||||
# Entity type triple
|
||||
Triple(
|
||||
s=Value(value=recipe_uri, is_uri=True),
|
||||
p=Value(value=rdf_type, is_uri=True),
|
||||
o=Value(value="http://purl.org/ontology/fo/Recipe", is_uri=True)
|
||||
),
|
||||
|
||||
# Label triple (automatic)
|
||||
Triple(
|
||||
s=Value(value=recipe_uri, is_uri=True),
|
||||
p=Value(value=rdfs_label, is_uri=True),
|
||||
o=Value(value="Cornish pasty recipe", is_uri=False)
|
||||
),
|
||||
|
||||
# Attribute triples (objects are literals, not URIs)
|
||||
Triple(
|
||||
s=Value(value=recipe_uri, is_uri=True),
|
||||
p=Value(value=serves_uri, is_uri=True),
|
||||
o=Value(value="4-6 people", is_uri=False) # Literal value!
|
||||
),
|
||||
Triple(
|
||||
s=Value(value=recipe_uri, is_uri=True),
|
||||
p=Value(value=prep_time_uri, is_uri=True),
|
||||
o=Value(value="45 minutes", is_uri=False) # Literal value!
|
||||
)
|
||||
]
|
||||
```
|
||||
|
||||
**मुख्य बातें:**
|
||||
एलएलएम शाब्दिक मानों को निकालता है: `"4-6 people"`, `"45 minutes"`
|
||||
एलएलएम अस्पष्टता को दूर करने के लिए इकाई प्रकार को शामिल करता है: `entity-type`
|
||||
एलएलएम स्कीमा से विशेषता नाम का उपयोग करता है: `"serves"`, `"preparation_time"`
|
||||
कोड ऑन्टोलॉजी डेटाटाइप गुणों से विशेषता यूआरआई को देखता है
|
||||
**ऑब्जेक्ट शाब्दिक है** (`is_uri=False`), कोई यूआरआई संदर्भ नहीं है
|
||||
मान प्राकृतिक पाठ के रूप में रहते हैं, किसी सामान्यीकरण की आवश्यकता नहीं है
|
||||
|
||||
**संबंधों से अंतर:**
|
||||
संबंध: विषय और वस्तु दोनों इकाइयाँ (यूआरआई) हैं
|
||||
विशेषताएँ: विषय इकाई (यूआरआई) है, वस्तु शाब्दिक मान (स्ट्रिंग/संख्या) है
|
||||
|
||||
### संपूर्ण उदाहरण: इकाइयाँ + संबंध + विशेषताएँ
|
||||
|
||||
**इनपुट टेक्स्ट:**
|
||||
```
|
||||
Cornish pasty is a savory pastry filled with beef and potatoes.
|
||||
This recipe serves 4 people.
|
||||
```
|
||||
|
||||
**एलएलएम क्या लौटाता है:**
|
||||
```json
|
||||
{
|
||||
"entities": [
|
||||
{
|
||||
"entity": "Cornish pasty",
|
||||
"type": "Recipe"
|
||||
},
|
||||
{
|
||||
"entity": "beef",
|
||||
"type": "Food"
|
||||
},
|
||||
{
|
||||
"entity": "potatoes",
|
||||
"type": "Food"
|
||||
}
|
||||
],
|
||||
"relationships": [
|
||||
{
|
||||
"subject": "Cornish pasty",
|
||||
"subject-type": "Recipe",
|
||||
"relation": "has_ingredient",
|
||||
"object": "beef",
|
||||
"object-type": "Food"
|
||||
},
|
||||
{
|
||||
"subject": "Cornish pasty",
|
||||
"subject-type": "Recipe",
|
||||
"relation": "has_ingredient",
|
||||
"object": "potatoes",
|
||||
"object-type": "Food"
|
||||
}
|
||||
],
|
||||
"attributes": [
|
||||
{
|
||||
"entity": "Cornish pasty",
|
||||
"entity-type": "Recipe",
|
||||
"attribute": "serves",
|
||||
"value": "4 people"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**परिणाम:** 11 आरडीएफ त्रिगुण उत्पन्न हुए:
|
||||
3 इकाई प्रकार त्रिगुण (rdf:type)
|
||||
3 इकाई लेबल त्रिगुण (rdfs:label) - स्वचालित
|
||||
2 संबंध त्रिगुण (has_ingredient)
|
||||
1 विशेषता त्रिगुण (serves)
|
||||
|
||||
ये सभी एलएलएम द्वारा सरल, प्राकृतिक भाषा निष्कर्षण से प्राप्त हुए!
|
||||
|
||||
## संदर्भ
|
||||
|
||||
वर्तमान कार्यान्वयन: `trustgraph-flow/trustgraph/extract/kg/ontology/extract.py`
|
||||
प्रॉम्प्ट टेम्पलेट: `ontology-prompt.md`
|
||||
परीक्षण मामले: `tests/unit/test_extract/test_ontology/`
|
||||
उदाहरण ऑन्टोलॉजी: `e2e/test-data/food.ontology`
|
||||
188
docs/tech-specs/hi/ontology.hi.md
Normal file
188
docs/tech-specs/hi/ontology.hi.md
Normal file
|
|
@ -0,0 +1,188 @@
|
|||
---
|
||||
layout: default
|
||||
title: "ऑन्टोलॉजी संरचना तकनीकी विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# ऑन्टोलॉजी संरचना तकनीकी विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह विनिर्देश ट्रस्टग्राफ सिस्टम के भीतर ऑन्टोलॉजी की संरचना और प्रारूप का वर्णन करता है। ऑन्टोलॉजी औपचारिक ज्ञान मॉडल प्रदान करते हैं जो क्लास, गुण और संबंधों को परिभाषित करते हैं, और तर्क और अनुमान क्षमताओं का समर्थन करते हैं। सिस्टम एक OWL-प्रेरित कॉन्फ़िगरेशन प्रारूप का उपयोग करता है जो व्यापक रूप से OWL/RDFS अवधारणाओं का प्रतिनिधित्व करता है, जबकि ट्रस्टग्राफ की आवश्यकताओं के लिए अनुकूलित है।
|
||||
|
||||
**नामकरण सम्मेलन**: यह परियोजना सभी पहचानकर्ताओं (कॉन्फ़िगरेशन कुंजियों, API एंडपॉइंट, मॉड्यूल नामों, आदि) के लिए "केबब-केस" का उपयोग करती है, न कि "स्नेक_केस" का।
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
- **क्लास और प्रॉपर्टी प्रबंधन**: OWL-जैसी क्लास को प्रॉपर्टी, डोमेन, रेंज और टाइप बाधाओं के साथ परिभाषित करें।
|
||||
- **समृद्ध शब्दार्थ समर्थन**: व्यापक RDFS/OWL प्रॉपर्टी सहित लेबल, बहु-भाषा समर्थन और औपचारिक बाधाओं को सक्षम करें।
|
||||
- **बहु-ऑन्टोलॉजी समर्थन**: कई ऑन्टोलॉजी को एक साथ मौजूद रहने और इंटरऑपरेट करने की अनुमति दें।
|
||||
- **सत्यापन और तर्क**: सुनिश्चित करें कि ऑन्टोलॉजी OWL-जैसी मानकों के अनुरूप हैं, जिसमें स्थिरता जांच और अनुमान समर्थन शामिल है।
|
||||
- **मानक अनुकूलता**: मानक प्रारूपों (टर्टल, RDF/XML, OWL/XML) में आयात/निर्यात का समर्थन करें, जबकि आंतरिक अनुकूलन बनाए रखें।
|
||||
|
||||
## पृष्ठभूमि
|
||||
|
||||
ट्रस्टग्राफ ऑन्टोलॉजी को एक लचीली कुंजी-मान्य सिस्टम में कॉन्फ़िगरेशन आइटम के रूप में संग्रहीत करता है। जबकि प्रारूप OWL (वेब ऑन्टोलॉजी लैंग्वेज) से प्रेरित है, यह ट्रस्टग्राफ के विशिष्ट उपयोग के मामलों के लिए अनुकूलित है और सभी OWL विनिर्देशों का सख्ती से पालन नहीं करता है।
|
||||
|
||||
ट्रस्टग्राफ में ऑन्टोलॉजी निम्नलिखित को सक्षम करते हैं:
|
||||
- औपचारिक ऑब्जेक्ट प्रकारों और उनके गुणों की परिभाषा
|
||||
- प्रॉपर्टी डोमेन, रेंज और टाइप बाधाओं का विनिर्देश
|
||||
- तार्किक तर्क और अनुमान
|
||||
- जटिल संबंध और कार्डिनैलिटी बाधाएं
|
||||
- अंतर्राष्ट्रीयकरण के लिए बहु-भाषा समर्थन
|
||||
|
||||
## ऑन्टोलॉजी संरचना
|
||||
|
||||
### कॉन्फ़िगरेशन भंडारण
|
||||
|
||||
ऑन्टोलॉजी को निम्नलिखित पैटर्न के साथ कॉन्फ़िगरेशन आइटम के रूप में संग्रहीत किया जाता है:
|
||||
- **टाइप**: `ऑन्टोलॉजी`
|
||||
- **कुंजी**: अद्वितीय ऑन्टोलॉजी पहचानकर्ता (जैसे, `प्राकृतिक-दुनिया`, `डोमेन-मॉडल`)
|
||||
- **मान**: JSON प्रारूप में पूरी ऑन्टोलॉजी
|
||||
|
||||
### JSON संरचना
|
||||
|
||||
ऑन्टोलॉजी JSON प्रारूप में चार मुख्य अनुभाग होते हैं:
|
||||
|
||||
#### 1. मेटाडेटा
|
||||
|
||||
ऑन्टोलॉजी के बारे में प्रशासनिक और वर्णनात्मक जानकारी शामिल है:
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"नाम": "प्राकृतिक दुनिया",
|
||||
"विवरण": "प्राकृतिक क्रम को कवर करने वाली ऑन्टोलॉजी",
|
||||
"संस्करण": "1.0.0",
|
||||
"बनाया गया": "2025-09-20T12:07:37.068Z",
|
||||
"संशोधित": "2025-09-20T12:12:20.725Z",
|
||||
"निर्माता": "वर्तमान-उपयोगकर्ता",
|
||||
"नेमस्पेस": "http://trustgraph.ai/ontologies/natural-world",
|
||||
"आयात": ["http://www.w3.org/2002/07/owl#"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**फ़ील्ड:**
|
||||
- `नाम`: ऑन्टोलॉजी का मानव-पठनीय नाम
|
||||
- `विवरण`: ऑन्टोलॉजी के उद्देश्य का संक्षिप्त विवरण
|
||||
- `संस्करण`: सिमेंटिक संस्करण संख्या
|
||||
- `बनाया गया`: निर्माण का ISO 8601 टाइमस्टैम्प
|
||||
- `संशोधित`: अंतिम संशोधन का ISO 8601 टाइमस्टैम्प
|
||||
- `निर्माता`: निर्माता उपयोगकर्ता/सिस्टम की पहचान
|
||||
- `नेमस्पेस`: ऑन्टोलॉजी तत्वों के लिए आधार URI
|
||||
- `आयात`: आयातित ऑन्टोलॉजी URI का सरणी
|
||||
|
||||
#### 2. क्लास
|
||||
|
||||
ऑब्जेक्ट प्रकार और उनके पदानुक्रमित संबंधों को परिभाषित करता है:
|
||||
|
||||
```json
|
||||
{
|
||||
"क्लास": {
|
||||
"जानवर": {
|
||||
"URI": "http://trustgraph.ai/ontologies/natural-world#animal",
|
||||
"टाइप": "owl:Class",
|
||||
"rdfs:लेबल": [{"मान": "जानवर", "भाषा": "en"}],
|
||||
"rdfs:टिप्पणी": "एक जानवर",
|
||||
"rdfs:उपवर्ग": "जीवनरूप",
|
||||
"owl:समतुल्यक्लास": ["प्राणी"],
|
||||
"owl:भिन्न": ["पौधा"],
|
||||
"dcterms:पहचानकर्ता": "ANI-001"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**समर्थित प्रॉपर्टी:**
|
||||
- `URI`: क्लास का पूरा URI
|
||||
- `टाइप`: `owl:Class`
|
||||
- `rdfs:लेबल`: क्लास का लेबल
|
||||
- `rdfs:टिप्पणी`: क्लास का विवरण
|
||||
- `rdfs:उपवर्ग`: पैरेंट क्लास
|
||||
- `owl:समतुल्यक्लास`: समान क्लास
|
||||
- `owl:भिन्न`: अलग क्लास
|
||||
- `dcterms:पहचानकर्ता`: क्लास का पहचानकर्ता
|
||||
|
||||
#### 3. ऑब्जेक्ट प्रॉपर्टी
|
||||
|
||||
ऑब्जेक्ट और उनके गुणों के बीच संबंधों को परिभाषित करता है:
|
||||
|
||||
```json
|
||||
{
|
||||
"ऑब्जेक्टप्रॉपर्टी": {
|
||||
"hasPart": {
|
||||
"URI": "http://trustgraph.ai/ontologies/natural-world#hasPart",
|
||||
"टाइप": "owl:ObjectProperty",
|
||||
"rdfs:लेबल": [{"मान": "hasPart", "भाषा": "en"}],
|
||||
"rdfs:टिप्पणी": "यह दर्शाता है कि एक ऑब्जेक्ट का एक भाग है"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**समर्थित प्रॉपर्टी:**
|
||||
- `URI`: प्रॉपर्टी का पूरा URI
|
||||
- `टाइप`: `owl:ObjectProperty` या `owl:DatatypeProperty`
|
||||
- `rdfs:लेबल`: प्रॉपर्टी का लेबल
|
||||
- `rdfs:टिप्पणी`: प्रॉपर्टी का विवरण
|
||||
|
||||
#### 4. डेटाटाइप प्रॉपर्टी
|
||||
|
||||
ऑब्जेक्ट के डेटा मानों को परिभाषित करता है:
|
||||
|
||||
```json
|
||||
{
|
||||
"डेटाटाइप्रॉपर्टी": {
|
||||
"नंबरऑफलेग्स": {
|
||||
"URI": "http://trustgraph.ai/ontologies/natural-world#number-of-legs",
|
||||
"टाइप": "owl:DatatypeProperty",
|
||||
"rdfs:लेबल": [{"मान": "नंबर-ऑफ-लेग्स", "भाषा": "en"}],
|
||||
"rdfs:टिप्पणी": "जानवर की पैर की संख्या",
|
||||
"rdfs:डोमेन": "जानवर"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**समर्थित प्रॉपर्टी:**
|
||||
- `URI`: प्रॉपर्टी का पूरा URI
|
||||
- `टाइप`: `owl:DatatypeProperty`
|
||||
- `rdfs:लेबल`: प्रॉपर्टी का लेबल
|
||||
- `rdfs:टिप्पणी`: प्रॉपर्टी का विवरण
|
||||
- `rdfs:डोमेन`: प्रॉपर्टी का डोमेन
|
||||
|
||||
## सत्यापन नियम
|
||||
|
||||
### संरचनात्मक सत्यापन
|
||||
|
||||
1. **URI संगति**: सभी URI `{नेमस्पेस}#{पहचानकर्ता}` पैटर्न का पालन करना चाहिए।
|
||||
2. **क्लास पदानुक्रम**: `rdfs:उपवर्ग` में कोई गोलाकार वंश नहीं होना चाहिए।
|
||||
3. **प्रॉपर्टी डोमेन/रेंज**: मौजूदा क्लास या मान्य XSD प्रकारों को संदर्भित करना चाहिए।
|
||||
4. **भिन्न वर्ग**: एक दूसरे के उपवर्ग नहीं हो सकते।
|
||||
5. **उलटा प्रॉपर्टी**: यदि निर्दिष्ट है, तो द्विदिश होना चाहिए।
|
||||
|
||||
### शब्दार्थ सत्यापन
|
||||
|
||||
1. **अद्वितीय पहचानकर्ता**: क्लास और प्रॉपर्टी पहचानकर्ता ऑन्टोलॉजी के भीतर अद्वितीय होने चाहिए।
|
||||
2. **भाषा टैग**: BCP 47 भाषा टैग प्रारूप का पालन करना चाहिए।
|
||||
3. **कार्डिनैलिटी बाधाएं**: जब दोनों निर्दिष्ट हों, तो `minCardinality` ≤ `maxCardinality` होना चाहिए।
|
||||
4. **कार्यात्मक प्रॉपर्टी**: `maxCardinality` > 1 नहीं हो सकता।
|
||||
|
||||
## आयात/निर्यात प्रारूप समर्थन
|
||||
|
||||
जबकि आंतरिक प्रारूप JSON है, सिस्टम मानक ऑन्टोलॉजी प्रारूपों में रूपांतरण का समर्थन करता है:
|
||||
|
||||
- **टर्टल (.ttl)** - कॉम्पैक्ट RDF क्रमबद्धता
|
||||
- **RDF/XML (.rdf, .owl)** - W3C मानक प्रारूप
|
||||
- **OWL/XML (.owx)** - OWL-विशिष्ट XML प्रारूप
|
||||
- **JSON-LD (.jsonld)** - लिंक्ड डेटा के लिए JSON
|
||||
|
||||
## संदर्भ
|
||||
|
||||
- [OWL 2 वेब ऑन्टोलॉजी भाषा](https://www.w3.org/TR/owl2-overview/)
|
||||
- [RDF स्कीमा 1.1](https://www.w3.org/TR/rdf-schema/)
|
||||
- [XML स्कीमा डेटाटाइप](https://www.w3.org/TR/xmlschema-2/)
|
||||
- [BCP 47 भाषा टैग](https://tools.ietf.org/html/bcp47)
|
||||
1075
docs/tech-specs/hi/ontorag.hi.md
Normal file
1075
docs/tech-specs/hi/ontorag.hi.md
Normal file
File diff suppressed because it is too large
Load diff
239
docs/tech-specs/hi/openapi-spec.hi.md
Normal file
239
docs/tech-specs/hi/openapi-spec.hi.md
Normal file
|
|
@ -0,0 +1,239 @@
|
|||
---
|
||||
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`
|
||||
965
docs/tech-specs/hi/pubsub.hi.md
Normal file
965
docs/tech-specs/hi/pubsub.hi.md
Normal file
|
|
@ -0,0 +1,965 @@
|
|||
---
|
||||
layout: default
|
||||
title: "पब/सब इंफ्रास्ट्रक्चर"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# पब/सब इंफ्रास्ट्रक्चर
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह दस्तावेज़ ट्रस्टग्राफ कोडबेस और पब/सब इंफ्रास्ट्रक्चर के बीच सभी कनेक्शनों को सूचीबद्ध करता है। वर्तमान में, सिस्टम को अपाचे पल्सर का उपयोग करने के लिए हार्डकोड किया गया है। यह विश्लेषण सभी एकीकरण बिंदुओं की पहचान करता है ताकि एक कॉन्फ़िगर करने योग्य पब/सब एब्स्ट्रैक्शन की ओर भविष्य के रीफैक्टरिंग को सूचित किया जा सके।
|
||||
|
||||
## वर्तमान स्थिति: पल्सर एकीकरण बिंदु
|
||||
|
||||
### 1. डायरेक्ट पल्सर क्लाइंट उपयोग
|
||||
|
||||
**स्थान:** `trustgraph-flow/trustgraph/gateway/service.py`
|
||||
|
||||
एपीआई गेटवे सीधे पल्सर क्लाइंट को आयात और इंस्टेंट करता है:
|
||||
|
||||
**पंक्ति 20:** `import pulsar`
|
||||
**पंक्तियाँ 54-61:** `pulsar.Client()` का प्रत्यक्ष इंस्टेंटेशन, वैकल्पिक `pulsar.AuthenticationToken()` के साथ
|
||||
**पंक्तियाँ 33-35:** पर्यावरण चर से डिफ़ॉल्ट पल्सर होस्ट कॉन्फ़िगरेशन
|
||||
**पंक्तियाँ 178-192:** `--pulsar-host`, `--pulsar-api-key` और `--pulsar-listener` के लिए CLI तर्क
|
||||
**पंक्तियाँ 78, 124:** `pulsar_client` को `ConfigReceiver` और `DispatcherManager` को पास करता है
|
||||
|
||||
यह एकमात्र स्थान है जहां पल्सर क्लाइंट को एब्स्ट्रैक्शन लेयर के बाहर सीधे इंस्टेंट किया गया है।
|
||||
|
||||
### 2. बेस प्रोसेसर फ्रेमवर्क
|
||||
|
||||
**स्थान:** `trustgraph-base/trustgraph/base/async_processor.py`
|
||||
|
||||
सभी प्रोसेसर के लिए बेस क्लास पल्सर कनेक्टिविटी प्रदान करता है:
|
||||
|
||||
**पंक्ति 9:** `import _pulsar` (अपवाद हैंडलिंग के लिए)
|
||||
**पंक्ति 18:** `from . pubsub import PulsarClient`
|
||||
**पंक्ति 38:** `pulsar_client_object = PulsarClient(**params)` बनाता है
|
||||
**पंक्तियाँ 104-108:** गुण जो `pulsar_host` और `pulsar_client` को उजागर करते हैं
|
||||
**पंक्ति 250:** स्थैतिक विधि `add_args()` CLI तर्कों के लिए `PulsarClient.add_args(parser)` को कॉल करता है
|
||||
**पंक्तियाँ 223-225:** `_pulsar.Interrupted` के लिए अपवाद हैंडलिंग
|
||||
|
||||
सभी प्रोसेसर `AsyncProcessor` से इनहेरिट करते हैं, जिससे यह केंद्रीय एकीकरण बिंदु बन जाता है।
|
||||
|
||||
### 3. उपभोक्ता एब्स्ट्रैक्शन
|
||||
|
||||
**स्थान:** `trustgraph-base/trustgraph/base/consumer.py`
|
||||
|
||||
यह कतारों से संदेशों का उपभोग करता है और हैंडलर फ़ंक्शन को लागू करता है:
|
||||
|
||||
**पल्सर आयात:**
|
||||
**पंक्ति 12:** `from pulsar.schema import JsonSchema`
|
||||
**पंक्ति 13:** `import pulsar`
|
||||
**पंक्ति 14:** `import _pulsar`
|
||||
|
||||
**पल्सर-विशिष्ट उपयोग:**
|
||||
**पंक्तियाँ 100, 102:** `pulsar.InitialPosition.Earliest` / `pulsar.InitialPosition.Latest`
|
||||
**पंक्ति 108:** `JsonSchema(self.schema)` रैपर
|
||||
**पंक्ति 110:** `pulsar.ConsumerType.Shared`
|
||||
**पंक्तियाँ 104-111:** पल्सर-विशिष्ट मापदंडों के साथ `self.client.subscribe()`
|
||||
**पंक्तियाँ 143, 150, 65:** `consumer.unsubscribe()` और `consumer.close()` विधियाँ
|
||||
**पंक्ति 162:** `_pulsar.Timeout` अपवाद
|
||||
**पंक्तियाँ 182, 205, 232:** `consumer.acknowledge()` / `consumer.negative_acknowledge()`
|
||||
|
||||
**स्पेक फ़ाइल:** `trustgraph-base/trustgraph/base/consumer_spec.py`
|
||||
**पंक्ति 22:** `processor.pulsar_client` को संदर्भित करता है
|
||||
|
||||
### 4. उत्पादक एब्स्ट्रैक्शन
|
||||
|
||||
**स्थान:** `trustgraph-base/trustgraph/base/producer.py`
|
||||
|
||||
यह कतारों में संदेश भेजता है:
|
||||
|
||||
**पल्सर आयात:**
|
||||
**पंक्ति 2:** `from pulsar.schema import JsonSchema`
|
||||
|
||||
**पल्सर-विशिष्ट उपयोग:**
|
||||
**पंक्ति 49:** `JsonSchema(self.schema)` रैपर
|
||||
**पंक्तियाँ 47-51:** पल्सर-विशिष्ट मापदंडों (विषय, स्कीमा, चंकिंग_सक्षम) के साथ `self.client.create_producer()`
|
||||
**पंक्तियाँ 31, 76:** `producer.close()` विधि
|
||||
**पंक्तियाँ 64-65:** संदेश और गुणों के साथ `producer.send()`
|
||||
|
||||
**स्पेक फ़ाइल:** `trustgraph-base/trustgraph/base/producer_spec.py`
|
||||
**पंक्ति 18:** `processor.pulsar_client` को संदर्भित करता है
|
||||
|
||||
### 5. प्रकाशक एब्स्ट्रैक्शन
|
||||
|
||||
**स्थान:** `trustgraph-base/trustgraph/base/publisher.py`
|
||||
|
||||
यह कतार बफरिंग के साथ एसिंक्रोनस संदेश प्रकाशन है:
|
||||
|
||||
**पल्सर आयात:**
|
||||
**पंक्ति 2:** `from pulsar.schema import JsonSchema`
|
||||
**पंक्ति 6:** `import pulsar`
|
||||
|
||||
**पल्सर-विशिष्ट उपयोग:**
|
||||
**पंक्ति 52:** `JsonSchema(self.schema)` रैपर
|
||||
**पंक्तियाँ 50-54:** पल्सर-विशिष्ट मापदंडों के साथ `self.client.create_producer()`
|
||||
**पंक्तियाँ 101, 103:** संदेश और वैकल्पिक गुणों के साथ `producer.send()`
|
||||
**पंक्तियाँ 106-107:** `producer.flush()` और `producer.close()` विधियाँ
|
||||
|
||||
### 6. सब्सक्राइबर एब्स्ट्रैक्शन
|
||||
|
||||
**स्थान:** `trustgraph-base/trustgraph/base/subscriber.py`
|
||||
|
||||
यह क्यूज़ से मल्टी-रिसीवर मैसेज डिस्ट्रीब्यूशन प्रदान करता है:
|
||||
|
||||
**पल्सर इम्पोर्ट्स:**
|
||||
**लाइन 6:** `from pulsar.schema import JsonSchema`
|
||||
**लाइन 8:** `import _pulsar`
|
||||
|
||||
**पल्सर-विशिष्ट उपयोग:**
|
||||
**लाइन 55:** `JsonSchema(self.schema)` रैपर
|
||||
**लाइन 57:** `self.client.subscribe(**subscribe_args)`
|
||||
**लाइनें 101, 136, 160, 167-172:** पल्सर अपवाद: `_pulsar.Timeout`, `_pulsar.InvalidConfiguration`, `_pulsar.AlreadyClosed`
|
||||
**लाइनें 159, 166, 170:** उपभोक्ता विधियाँ: `negative_acknowledge()`, `unsubscribe()`, `close()`
|
||||
**लाइनें 247, 251:** मैसेज स्वीकृति: `acknowledge()`, `negative_acknowledge()`
|
||||
|
||||
**स्पेक फाइल:** `trustgraph-base/trustgraph/base/subscriber_spec.py`
|
||||
**लाइन 19:** संदर्भ `processor.pulsar_client`
|
||||
|
||||
### 7. स्कीमा सिस्टम (हार्ट ऑफ डार्कनेस)
|
||||
|
||||
**स्थान:** `trustgraph-base/trustgraph/schema/`
|
||||
|
||||
सिस्टम में हर मैसेज स्कीमा पल्सर के स्कीमा फ्रेमवर्क का उपयोग करके परिभाषित किया गया है।
|
||||
|
||||
**कोर प्रिमिटिव्स:** `schema/core/primitives.py`
|
||||
**लाइन 2:** `from pulsar.schema import Record, String, Boolean, Array, Integer`
|
||||
सभी स्कीमा पल्सर के `Record` बेस क्लास से इनहेरिट होते हैं
|
||||
सभी फ़ील्ड प्रकार पल्सर प्रकार हैं: `String()`, `Integer()`, `Boolean()`, `Array()`, `Map()`, `Double()`
|
||||
|
||||
**उदाहरण स्कीमा:**
|
||||
`schema/services/llm.py` (लाइन 2): `from pulsar.schema import Record, String, Array, Double, Integer, Boolean`
|
||||
`schema/services/config.py` (लाइन 2): `from pulsar.schema import Record, Bytes, String, Boolean, Array, Map, Integer`
|
||||
|
||||
**टॉपिक नामकरण:** `schema/core/topic.py`
|
||||
**लाइनें 2-3:** टॉपिक फॉर्मेट: `{kind}://{tenant}/{namespace}/{topic}`
|
||||
यह URI संरचना पल्सर-विशिष्ट है (जैसे, `persistent://tg/flow/config`)
|
||||
|
||||
**प्रभाव:**
|
||||
पूरे कोडबेस में सभी अनुरोध/प्रतिक्रिया मैसेज परिभाषाएँ पल्सर स्कीमा का उपयोग करती हैं
|
||||
इसमें निम्नलिखित के लिए सेवाएँ शामिल हैं: कॉन्फ़िग, फ्लो, एलएलएम, प्रॉम्प्ट, क्वेरी, स्टोरेज, एजेंट, कलेक्शन, डायग्नोसिस, लाइब्रेरी, लुकअप, एनएलपी_क्वेरी, ऑब्जेक्ट्स_क्वेरी, रिट्रीवल, स्ट्रक्चर्ड_क्वेरी
|
||||
स्कीमा परिभाषाएँ सभी प्रोसेसर और सेवाओं में आयात की जाती हैं और व्यापक रूप से उपयोग की जाती हैं
|
||||
|
||||
## सारांश
|
||||
|
||||
### श्रेणी के अनुसार पल्सर निर्भरताएँ
|
||||
|
||||
1. **क्लाइंट इंस्टेंशिएशन:**
|
||||
सीधा: `gateway/service.py`
|
||||
अमूर्त: `async_processor.py` → `pubsub.py` (PulsarClient)
|
||||
|
||||
2. **मैसेज ट्रांसपोर्ट:**
|
||||
उपभोक्ता: `consumer.py`, `consumer_spec.py`
|
||||
उत्पादक: `producer.py`, `producer_spec.py`
|
||||
प्रकाशक: `publisher.py`
|
||||
सब्सक्राइबर: `subscriber.py`, `subscriber_spec.py`
|
||||
|
||||
3. **स्कीमा सिस्टम:**
|
||||
बेस प्रकार: `schema/core/primitives.py`
|
||||
सभी सेवा स्कीमा: `schema/services/*.py`
|
||||
टॉपिक नामकरण: `schema/core/topic.py`
|
||||
|
||||
4. **पल्सर-विशिष्ट अवधारणाएँ आवश्यक:**
|
||||
टॉपिक-आधारित मैसेजिंग
|
||||
स्कीमा सिस्टम (रिकॉर्ड, फ़ील्ड प्रकार)
|
||||
साझा सदस्यताएँ
|
||||
मैसेज स्वीकृति (सकारात्मक/नकारात्मक)
|
||||
उपभोक्ता पोजिशनिंग (सबसे पहले/नवीनतम)
|
||||
मैसेज प्रॉपर्टीज़
|
||||
प्रारंभिक पोजीशन और उपभोक्ता प्रकार
|
||||
चंकिंग सपोर्ट
|
||||
लगातार बनाम गैर-लगातार टॉपिक
|
||||
|
||||
### रिफैक्टरिंग चुनौतियाँ
|
||||
|
||||
अच्छी खबर: एब्स्ट्रैक्शन लेयर (उपभोक्ता, उत्पादक, प्रकाशक, सब्सक्राइबर) पल्सर इंटरैक्शन के अधिकांश पहलुओं को साफ-सुथरा रूप से एनकैप्सुलेट करता है।
|
||||
|
||||
चुनौतियाँ:
|
||||
1. **स्कीमा सिस्टम की सर्वव्यापकता:** हर मैसेज परिभाषा `pulsar.schema.Record` और पल्सर फ़ील्ड प्रकारों का उपयोग करती है
|
||||
2. **पल्सर-विशिष्ट एनम्स:** `InitialPosition`, `ConsumerType`
|
||||
3. **पल्सर अपवाद:** `_pulsar.Timeout`, `_pulsar.Interrupted`, `_pulsar.InvalidConfiguration`, `_pulsar.AlreadyClosed`
|
||||
4. **विधि हस्ताक्षर:** `acknowledge()`, `negative_acknowledge()`, `subscribe()`, `create_producer()`, आदि।
|
||||
5. **टॉपिक URI फॉर्मेट:** पल्सर की `kind://tenant/namespace/topic` संरचना
|
||||
|
||||
### अगले कदम
|
||||
|
||||
पब/सब इंफ्रास्ट्रक्चर को कॉन्फ़िगर करने योग्य बनाने के लिए, हमें:
|
||||
|
||||
1. क्लाइंट/स्कीमा सिस्टम के लिए एक एब्स्ट्रैक्शन इंटरफ़ेस बनाएं
|
||||
2. पल्सर-विशिष्ट एनम्स और अपवादों को अमूर्त करें
|
||||
3. स्कीमा रैपर या वैकल्पिक स्कीमा परिभाषाएँ बनाएँ
|
||||
4. पल्सर और वैकल्पिक सिस्टम (काफ्का, रैबिटएमक्यू, रेडिस स्ट्रीम्स, आदि) दोनों के लिए इंटरफ़ेस को लागू करें
|
||||
5. `pubsub.py` को कॉन्फ़िगर करने योग्य बनाएं और कई बैकएंड का समर्थन करें
|
||||
6. मौजूदा डिप्लॉयमेंट के लिए माइग्रेशन पाथ प्रदान करें
|
||||
|
||||
## दृष्टिकोण ड्राफ्ट 1: स्कीमा ट्रांसलेशन लेयर के साथ एडाप्टर पैटर्न
|
||||
|
||||
### मुख्य अंतर्दृष्टि
|
||||
**स्कीमा सिस्टम** एकीकरण का सबसे गहरा बिंदु है - बाकी सब कुछ इससे उपजा है। हमें पहले इसे हल करना होगा, अन्यथा हमें पूरे कोडबेस को फिर से लिखना होगा।
|
||||
|
||||
### रणनीति: न्यूनतम व्यवधान के साथ एडाप्टर
|
||||
|
||||
**1. पल्सर स्कीमा को आंतरिक प्रतिनिधित्व के रूप में बनाए रखें**
|
||||
सभी स्कीमा परिभाषाओं को फिर से न लिखें
|
||||
स्कीमा `pulsar.schema.Record` आंतरिक रूप से बने रहेंगे
|
||||
हमारे कोड और पब/सब बैकएंड के बीच की सीमा पर अनुवाद करने के लिए एडेप्टर का उपयोग करें
|
||||
|
||||
**2. एक पब/सब एब्स्ट्रैक्शन लेयर बनाएं:**
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Existing Code (unchanged) │
|
||||
│ - Uses Pulsar schemas internally │
|
||||
│ - Consumer/Producer/Publisher │
|
||||
└──────────────┬──────────────────────┘
|
||||
│
|
||||
┌──────────────┴──────────────────────┐
|
||||
│ PubSubFactory (configurable) │
|
||||
│ - Creates backend-specific client │
|
||||
└──────────────┬──────────────────────┘
|
||||
│
|
||||
┌──────┴──────┐
|
||||
│ │
|
||||
┌───────▼─────┐ ┌────▼─────────┐
|
||||
│ PulsarAdapter│ │ KafkaAdapter │ etc...
|
||||
│ (passthrough)│ │ (translates) │
|
||||
└──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
**3. अमूर्त इंटरफेस को परिभाषित करें:**
|
||||
`PubSubClient` - क्लाइंट कनेक्शन
|
||||
`PubSubProducer` - संदेश भेजना
|
||||
`PubSubConsumer` - संदेश प्राप्त करना
|
||||
`SchemaAdapter` - पल्सर स्कीमा को JSON या बैकएंड-विशिष्ट प्रारूपों में अनुवाद करना
|
||||
|
||||
**4. कार्यान्वयन विवरण:**
|
||||
|
||||
**पल्सर एडेप्टर के लिए:** लगभग सीधे, न्यूनतम अनुवाद
|
||||
|
||||
**अन्य बैकएंड के लिए** (Kafka, RabbitMQ, आदि):
|
||||
पल्सर रिकॉर्ड ऑब्जेक्ट को JSON/बाइट में क्रमबद्ध करें
|
||||
निम्नलिखित अवधारणाओं को मैप करें:
|
||||
`InitialPosition.Earliest/Latest` → Kafka का auto.offset.reset
|
||||
`acknowledge()` → Kafka का कमिट
|
||||
`negative_acknowledge()` → पुनः कतार या DLQ पैटर्न
|
||||
टॉपिक URI → बैकएंड-विशिष्ट टॉपिक नाम
|
||||
|
||||
### विश्लेषण
|
||||
|
||||
**लाभ:**
|
||||
✅ मौजूदा सेवाओं में न्यूनतम कोड परिवर्तन
|
||||
✅ स्कीमा अपरिवर्तित रहते हैं (कोई बड़ा पुनर्लेखन नहीं)
|
||||
✅ क्रमिक माइग्रेशन पथ
|
||||
✅ पल्सर उपयोगकर्ताओं को कोई अंतर दिखाई नहीं देता
|
||||
✅ एडेप्टर के माध्यम से नए बैकएंड जोड़े जा सकते हैं
|
||||
|
||||
**नुकसान:**
|
||||
⚠️ अभी भी पल्सर पर निर्भरता है (स्कीमा परिभाषाओं के लिए)
|
||||
⚠️ अवधारणाओं का अनुवाद करते समय कुछ असंगति
|
||||
|
||||
### वैकल्पिक विचार
|
||||
|
||||
एक **ट्रस्टग्राफ स्कीमा सिस्टम** बनाएं जो पब/सब से स्वतंत्र हो (डेटाक्लासेस या पाइडैंटिक का उपयोग करके), और फिर पल्सर/काफ्का/आदि स्कीमा को इससे उत्पन्न करें। इसके लिए प्रत्येक स्कीमा फ़ाइल को फिर से लिखना होगा और संभावित रूप से ब्रेकिंग परिवर्तन हो सकते हैं।
|
||||
|
||||
### ड्राफ्ट 1 के लिए अनुशंसा
|
||||
|
||||
**एडाप्टर दृष्टिकोण** से शुरुआत करें क्योंकि:
|
||||
1. यह व्यावहारिक है - मौजूदा कोड के साथ काम करता है
|
||||
2. यह न्यूनतम जोखिम के साथ अवधारणा को सिद्ध करता है
|
||||
3. यदि आवश्यक हो तो बाद में एक देशी स्कीमा सिस्टम में विकसित किया जा सकता है
|
||||
4. कॉन्फ़िगरेशन-संचालित: एक पर्यावरण चर बैकएंड को स्विच करता है
|
||||
|
||||
## दृष्टिकोण ड्राफ्ट 2: डेटाक्लासेस के साथ बैकएंड-अज्ञेय स्कीमा सिस्टम
|
||||
|
||||
### मुख्य अवधारणा
|
||||
|
||||
पायथन **डेटाक्लासेस** का उपयोग तटस्थ स्कीमा परिभाषा प्रारूप के रूप में करें। प्रत्येक पब/सब बैकएंड डेटाक्लासेस के लिए अपना सीरियललाइज़ेशन/डीसेरियलाइज़ेशन प्रदान करता है, जिससे पल्सर स्कीमा को कोडबेस में बने रहने की आवश्यकता समाप्त हो जाती है।
|
||||
|
||||
### फैक्ट्री स्तर पर स्कीमा बहुरूपता
|
||||
|
||||
पल्सर स्कीमा का अनुवाद करने के बजाय, **प्रत्येक बैकएंड अपनी स्कीमा हैंडलिंग प्रदान करता है** जो मानक पायथन डेटाक्लासेस के साथ काम करता है।
|
||||
|
||||
### प्रकाशक प्रवाह
|
||||
|
||||
```python
|
||||
# 1. Get the configured backend from factory
|
||||
pubsub = get_pubsub() # Returns PulsarBackend, MQTTBackend, etc.
|
||||
|
||||
# 2. Get schema class from the backend
|
||||
# (Can be imported directly - backend-agnostic)
|
||||
from trustgraph.schema.services.llm import TextCompletionRequest
|
||||
|
||||
# 3. Create a producer/publisher for a specific topic
|
||||
producer = pubsub.create_producer(
|
||||
topic="text-completion-requests",
|
||||
schema=TextCompletionRequest # Tells backend what schema to use
|
||||
)
|
||||
|
||||
# 4. Create message instances (same API regardless of backend)
|
||||
request = TextCompletionRequest(
|
||||
system="You are helpful",
|
||||
prompt="Hello world",
|
||||
streaming=False
|
||||
)
|
||||
|
||||
# 5. Send the message
|
||||
producer.send(request) # Backend serializes appropriately
|
||||
```
|
||||
|
||||
### उपभोक्ता प्रवाह
|
||||
|
||||
```python
|
||||
# 1. Get the configured backend
|
||||
pubsub = get_pubsub()
|
||||
|
||||
# 2. Create a consumer
|
||||
consumer = pubsub.subscribe(
|
||||
topic="text-completion-requests",
|
||||
schema=TextCompletionRequest # Tells backend how to deserialize
|
||||
)
|
||||
|
||||
# 3. Receive and deserialize
|
||||
msg = consumer.receive()
|
||||
request = msg.value() # Returns TextCompletionRequest dataclass instance
|
||||
|
||||
# 4. Use the data (type-safe access)
|
||||
print(request.system) # "You are helpful"
|
||||
print(request.prompt) # "Hello world"
|
||||
print(request.streaming) # False
|
||||
```
|
||||
|
||||
### पर्दे के पीछे क्या होता है
|
||||
|
||||
**पल्सर बैकएंड के लिए:**
|
||||
`create_producer()` → JSON स्कीमा या गतिशील रूप से उत्पन्न रिकॉर्ड के साथ पल्सर प्रोड्यूसर बनाता है
|
||||
`send(request)` → डेटाक्लास को JSON/पल्सर प्रारूप में क्रमबद्ध करता है, पल्सर को भेजता है
|
||||
`receive()` → पल्सर संदेश प्राप्त करता है, डेटाक्लास में वापस क्रमबद्ध करता है
|
||||
|
||||
**MQTT बैकएंड के लिए:**
|
||||
`create_producer()` → MQTT ब्रोकर से कनेक्ट होता है, स्कीमा पंजीकरण की आवश्यकता नहीं है
|
||||
`send(request)` → डेटाक्लास को JSON में परिवर्तित करता है, MQTT टॉपिक पर प्रकाशित करता है
|
||||
`receive()` → MQTT टॉपिक की सदस्यता लेता है, JSON को डेटाक्लास में क्रमबद्ध करता है
|
||||
|
||||
**Kafka बैकएंड के लिए:**
|
||||
`create_producer()` → Kafka प्रोड्यूसर बनाता है, यदि आवश्यक हो तो Avro स्कीमा पंजीकृत करता है
|
||||
`send(request)` → डेटाक्लास को Avro प्रारूप में क्रमबद्ध करता है, Kafka को भेजता है
|
||||
`receive()` → Kafka संदेश प्राप्त करता है, Avro को डेटाक्लास में वापस क्रमबद्ध करता है
|
||||
|
||||
### मुख्य डिज़ाइन बिंदु
|
||||
|
||||
1. **स्कीमा ऑब्जेक्ट निर्माण**: डेटाक्लास इंस्टेंस (`TextCompletionRequest(...)`) बैकएंड की परवाह किए बिना समान होता है
|
||||
2. **बैकएंड एन्कोडिंग को संभालता है**: प्रत्येक बैकएंड जानता है कि अपने डेटाक्लास को वायर प्रारूप में कैसे क्रमबद्ध करना है
|
||||
3. **निर्माण पर स्कीमा परिभाषा**: जब प्रोड्यूसर/कंज्यूमर बनाते हैं, तो आप स्कीमा प्रकार निर्दिष्ट करते हैं
|
||||
4. **टाइप सुरक्षा संरक्षित**: आपको एक उचित `TextCompletionRequest` ऑब्जेक्ट वापस मिलता है, कोई डिक्ट नहीं
|
||||
5. **कोई बैकएंड रिसाव नहीं**: एप्लिकेशन कोड कभी भी बैकएंड-विशिष्ट लाइब्रेरीज़ को आयात नहीं करता है
|
||||
|
||||
### उदाहरण परिवर्तन
|
||||
|
||||
**वर्तमान (पल्सर-विशिष्ट):**
|
||||
```python
|
||||
# schema/services/llm.py
|
||||
from pulsar.schema import Record, String, Boolean, Integer
|
||||
|
||||
class TextCompletionRequest(Record):
|
||||
system = String()
|
||||
prompt = String()
|
||||
streaming = Boolean()
|
||||
```
|
||||
|
||||
**नया (बैकएंड-स्वतंत्र):**
|
||||
```python
|
||||
# schema/services/llm.py
|
||||
from dataclasses import dataclass
|
||||
|
||||
@dataclass
|
||||
class TextCompletionRequest:
|
||||
system: str
|
||||
prompt: str
|
||||
streaming: bool = False
|
||||
```
|
||||
|
||||
### बैकएंड एकीकरण
|
||||
|
||||
प्रत्येक बैकएंड डेटाक्लासों का क्रमबद्धता/अक्रमबद्धता (सीरियलाइज़ेशन/डीसीरियलाइज़ेशन) संभालता है:
|
||||
|
||||
**पल्सर बैकएंड:**
|
||||
डेटाक्लासों से गतिशील रूप से `pulsar.schema.Record` क्लास उत्पन्न करें
|
||||
या डेटाक्लासों को JSON में क्रमबद्ध करें और पल्सर के JSON स्कीमा का उपयोग करें
|
||||
मौजूदा पल्सर डिप्लॉयमेंट के साथ संगतता बनाए रखता है
|
||||
|
||||
**MQTT/रेडिस बैकएंड:**
|
||||
डेटाक्लास उदाहरणों का सीधा JSON क्रमबद्धता
|
||||
`dataclasses.asdict()` / `from_dict()` का उपयोग करें
|
||||
हल्का, किसी स्कीमा रजिस्ट्री की आवश्यकता नहीं है
|
||||
|
||||
**काफ्का बैकएंड:**
|
||||
डेटाक्लास परिभाषाओं से एवरो स्कीमा उत्पन्न करें
|
||||
कॉन्फ्लुएंट की स्कीमा रजिस्ट्री का उपयोग करें
|
||||
स्कीमा विकास समर्थन के साथ टाइप-सुरक्षित क्रमबद्धता
|
||||
|
||||
### वास्तुकला
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Application Code │
|
||||
│ - Uses dataclass schemas │
|
||||
│ - Backend-agnostic │
|
||||
└──────────────┬──────────────────────┘
|
||||
│
|
||||
┌──────────────┴──────────────────────┐
|
||||
│ PubSubFactory (configurable) │
|
||||
│ - get_pubsub() returns backend │
|
||||
└──────────────┬──────────────────────┘
|
||||
│
|
||||
┌──────┴──────┐
|
||||
│ │
|
||||
┌───────▼─────────┐ ┌────▼──────────────┐
|
||||
│ PulsarBackend │ │ MQTTBackend │
|
||||
│ - JSON schema │ │ - JSON serialize │
|
||||
│ - or dynamic │ │ - Simple queues │
|
||||
│ Record gen │ │ │
|
||||
└─────────────────┘ └───────────────────┘
|
||||
```
|
||||
|
||||
### कार्यान्वयन विवरण
|
||||
|
||||
**1. स्कीमा परिभाषाएँ:** साधारण डेटाक्लास, टाइप हिंट के साथ
|
||||
`str`, `int`, `bool`, `float` मूल डेटा प्रकारों के लिए
|
||||
`list[T]` सरणियों के लिए
|
||||
`dict[str, T]` मानचित्रों के लिए
|
||||
जटिल प्रकारों के लिए नेस्टेड डेटाक्लास
|
||||
|
||||
**2. प्रत्येक बैकएंड निम्नलिखित प्रदान करता है:**
|
||||
सीरियलइज़र: `dataclass → bytes/wire format`
|
||||
डीसीरियलइज़र: `bytes/wire format → dataclass`
|
||||
स्कीमा पंजीकरण (यदि आवश्यक हो, जैसे कि Pulsar/Kafka)
|
||||
|
||||
**3. उपभोक्ता/उत्पादक सार:**
|
||||
पहले से मौजूद (consumer.py, producer.py)
|
||||
बैकएंड के सीरियलइज़ेशन का उपयोग करने के लिए अपडेट करें
|
||||
सीधे Pulsar आयात को हटा दें
|
||||
|
||||
**4. टाइप मैपिंग:**
|
||||
Pulsar `String()` → Python `str`
|
||||
Pulsar `Integer()` → Python `int`
|
||||
Pulsar `Boolean()` → Python `bool`
|
||||
Pulsar `Array(T)` → Python `list[T]`
|
||||
Pulsar `Map(K, V)` → Python `dict[K, V]`
|
||||
Pulsar `Double()` → Python `float`
|
||||
Pulsar `Bytes()` → Python `bytes`
|
||||
|
||||
### माइग्रेशन पथ
|
||||
|
||||
1. `trustgraph/schema/` में सभी स्कीमा के डेटाक्लास संस्करण बनाएं
|
||||
2. बैकएंड-प्रदान सीरियलइज़ेशन का उपयोग करने के लिए (उपभोक्ता, उत्पादक, प्रकाशक, ग्राहक) बैकएंड क्लास को अपडेट करें
|
||||
3. JSON स्कीमा या गतिशील रिकॉर्ड पीढ़ी के साथ PulsarBackend को लागू करें
|
||||
4. मौजूदा परिनियोजनों के साथ पिछड़े अनुकूलता सुनिश्चित करने के लिए Pulsar के साथ परीक्षण करें
|
||||
5. आवश्यकतानुसार नए बैकएंड (MQTT, Kafka, Redis, आदि) जोड़ें
|
||||
6. स्कीमा फ़ाइलों से Pulsar आयात को हटा दें
|
||||
|
||||
### लाभ
|
||||
|
||||
✅ **स्कीमा परिभाषाओं में कोई पब/सब निर्भरता नहीं**
|
||||
✅ **मानक Python** - समझने, टाइप-चेक करने और दस्तावेज़ बनाने में आसान
|
||||
✅ **आधुनिक टूलिंग** - mypy, IDE ऑटो-कंप्लीट, लिंटर के साथ काम करता है
|
||||
✅ **बैकएंड-अनुकूलित** - प्रत्येक बैकएंड देशी सीरियलइज़ेशन का उपयोग करता है
|
||||
✅ **कोई अनुवाद ओवरहेड नहीं** - सीधा सीरियलइज़ेशन, कोई एडेप्टर नहीं
|
||||
✅ **टाइप सुरक्षा** - उचित प्रकारों के साथ वास्तविक ऑब्जेक्ट
|
||||
✅ **आसान सत्यापन** - यदि आवश्यक हो तो Pydantic का उपयोग कर सकते हैं
|
||||
|
||||
### चुनौतियाँ और समाधान
|
||||
|
||||
**चुनौती:** Pulsar का `Record` में रनटाइम फ़ील्ड सत्यापन होता है
|
||||
**समाधान:** यदि आवश्यक हो तो सत्यापन के लिए Pydantic डेटाक्लास का उपयोग करें, या `__post_init__` के साथ Python 3.10+ डेटाक्लास सुविधाओं का उपयोग करें
|
||||
|
||||
**चुनौती:** कुछ Pulsar-विशिष्ट विशेषताएं (जैसे `Bytes` प्रकार)
|
||||
**समाधान:** डेटाक्लास में `bytes` प्रकार पर मैप करें, बैकएंड उचित रूप से एन्कोडिंग को संभालता है
|
||||
|
||||
**चुनौती:** टॉपिक नामकरण (`persistent://tenant/namespace/topic`)
|
||||
**समाधान:** स्कीमा परिभाषाओं में टॉपिक नामों को सारगर्भित करें, बैकएंड उचित प्रारूप में परिवर्तित करता है
|
||||
|
||||
**चुनौती:** स्कीमा विकास और संस्करण
|
||||
**समाधान:** प्रत्येक बैकएंड अपनी क्षमताओं के अनुसार इसका प्रबंधन करता है (Pulsar स्कीमा संस्करण, Kafka स्कीमा रजिस्ट्री, आदि)
|
||||
|
||||
**चुनौती:** नेस्टेड जटिल प्रकार
|
||||
**समाधान:** नेस्टेड डेटाक्लास का उपयोग करें, बैकएंड पुनरावर्ती रूप से सीरियलइज़/डीसीरियलइज़ करते हैं
|
||||
|
||||
### डिज़ाइन निर्णय
|
||||
|
||||
1. **सादे डेटाक्लास या Pydantic?**
|
||||
✅ **निर्णय: सादे Python डेटाक्लास का उपयोग करें**
|
||||
सरल, कोई अतिरिक्त निर्भरता नहीं
|
||||
सत्यापन व्यावहारिक रूप से आवश्यक नहीं है
|
||||
समझना और बनाए रखना आसान है
|
||||
|
||||
2. **स्कीमा विकास:**
|
||||
✅ **निर्णय: कोई संस्करण तंत्र आवश्यक नहीं है**
|
||||
स्कीमा स्थिर और लंबे समय तक चलने वाले हैं
|
||||
अपडेट आमतौर पर नए फ़ील्ड जोड़ते हैं (पिछड़े संगत)
|
||||
बैकएंड अपनी क्षमताओं के अनुसार स्कीमा विकास को संभालते हैं
|
||||
|
||||
3. **पिछड़ी संगतता:**
|
||||
✅ **निर्णय: प्रमुख संस्करण परिवर्तन, पिछड़े संगतता की आवश्यकता नहीं है**
|
||||
यह एक ब्रेकिंग परिवर्तन होगा जिसमें माइग्रेशन निर्देश होंगे
|
||||
बेहतर डिज़ाइन के लिए स्वच्छ ब्रेक
|
||||
मौजूदा परिनियोजनों के लिए एक माइग्रेशन गाइड प्रदान किया जाएगा
|
||||
|
||||
4. **नेस्टेड प्रकार और जटिल संरचनाएं:**
|
||||
✅ **निर्णय: स्वाभाविक रूप से नेस्टेड डेटाक्लास का उपयोग करें**
|
||||
Python डेटाक्लास नेस्टिंग को पूरी तरह से संभालते हैं
|
||||
सरणियों के लिए `list[T]`, मानचित्रों के लिए `dict[K, V]`
|
||||
बैकएंड पुनरावर्ती रूप से सीरियलइज़/डीसीरियलइज़ करते हैं
|
||||
उदाहरण:
|
||||
```python
|
||||
@dataclass
|
||||
class Value:
|
||||
value: str
|
||||
is_uri: bool
|
||||
|
||||
@dataclass
|
||||
class Triple:
|
||||
s: Value # Nested dataclass
|
||||
p: Value
|
||||
o: Value
|
||||
|
||||
@dataclass
|
||||
class GraphQuery:
|
||||
triples: list[Triple] # Array of nested dataclasses
|
||||
metadata: dict[str, str]
|
||||
```
|
||||
|
||||
5. **डिफ़ॉल्ट मान और वैकल्पिक फ़ील्ड:**
|
||||
✅ **निर्णय: आवश्यक, डिफ़ॉल्ट और वैकल्पिक फ़ील्ड का मिश्रण**
|
||||
आवश्यक फ़ील्ड: कोई डिफ़ॉल्ट मान नहीं
|
||||
डिफ़ॉल्ट वाले फ़ील्ड: हमेशा मौजूद, उनका उचित डिफ़ॉल्ट मान होता है
|
||||
वास्तव में वैकल्पिक फ़ील्ड: `T | None = None`, जब `None` हो तो क्रमबद्धता से छोड़े जा सकते हैं
|
||||
उदाहरण:
|
||||
```python
|
||||
@dataclass
|
||||
class TextCompletionRequest:
|
||||
system: str # Required, no default
|
||||
prompt: str # Required, no default
|
||||
streaming: bool = False # Optional with default value
|
||||
metadata: dict | None = None # Truly optional, can be absent
|
||||
```
|
||||
|
||||
**महत्वपूर्ण क्रमबद्धता अर्थ:**
|
||||
|
||||
जब `metadata = None`:
|
||||
```json
|
||||
{
|
||||
"system": "...",
|
||||
"prompt": "...",
|
||||
"streaming": false
|
||||
// metadata field NOT PRESENT
|
||||
}
|
||||
```
|
||||
|
||||
जब `metadata = {}` (स्पष्ट रूप से खाली):
|
||||
```json
|
||||
{
|
||||
"system": "...",
|
||||
"prompt": "...",
|
||||
"streaming": false,
|
||||
"metadata": {} // Field PRESENT but empty
|
||||
}
|
||||
```
|
||||
|
||||
**मुख्य अंतर:**
|
||||
`None` → JSON में अनुपस्थित फ़ील्ड (सीरियलाइज़ नहीं किया गया)
|
||||
खाली मान (`{}`, `[]`, `""`) → फ़ील्ड मौजूद है लेकिन खाली मान के साथ
|
||||
यह अर्थपूर्ण रूप से महत्वपूर्ण है: "प्रदान नहीं किया गया" बनाम "स्पष्ट रूप से खाली"
|
||||
सीरियलाइज़ेशन बैकएंड को `None` फ़ील्ड को छोड़ना चाहिए, न कि इसे `null` के रूप में एन्कोड करना चाहिए
|
||||
|
||||
## दृष्टिकोण ड्राफ्ट 3: कार्यान्वयन विवरण
|
||||
|
||||
### सामान्य कतार नामकरण प्रारूप
|
||||
|
||||
बैकएंड-विशिष्ट कतार नामों को एक सामान्य प्रारूप से बदलें जिसे बैकएंड उचित रूप से मैप कर सकें।
|
||||
|
||||
**प्रारूप:** `{qos}/{tenant}/{namespace}/{queue-name}`
|
||||
|
||||
जहाँ:
|
||||
`qos`: सेवा की गुणवत्ता स्तर
|
||||
`q0` = बेस्ट-एफर्ट (फायर एंड फॉरगेट, कोई स्वीकृति नहीं)
|
||||
`q1` = एट-लीस्ट-वन्स (स्वीकृति की आवश्यकता होती है)
|
||||
`q2` = एग्ज़ैक्टली-वन्स (दो-चरण स्वीकृति)
|
||||
`tenant`: मल्टी-टेनेंसी के लिए तार्किक समूहीकरण
|
||||
`namespace`: किरायेदार के भीतर उप-समूहीकरण
|
||||
`queue-name`: वास्तविक कतार/विषय नाम
|
||||
|
||||
**उदाहरण:**
|
||||
```
|
||||
q1/tg/flow/text-completion-requests
|
||||
q2/tg/config/config-push
|
||||
q0/tg/metrics/stats
|
||||
```
|
||||
|
||||
### बैकएंड टॉपिक मैपिंग
|
||||
|
||||
प्रत्येक बैकएंड सामान्य प्रारूप को अपने मूल प्रारूप में परिवर्तित करता है:
|
||||
|
||||
**पल्सर बैकएंड:**
|
||||
```python
|
||||
def map_topic(self, generic_topic: str) -> str:
|
||||
# Parse: q1/tg/flow/text-completion-requests
|
||||
qos, tenant, namespace, queue = generic_topic.split('/', 3)
|
||||
|
||||
# Map QoS to persistence
|
||||
persistence = 'persistent' if qos in ['q1', 'q2'] else 'non-persistent'
|
||||
|
||||
# Return Pulsar URI: persistent://tg/flow/text-completion-requests
|
||||
return f"{persistence}://{tenant}/{namespace}/{queue}"
|
||||
```
|
||||
|
||||
**एमक्यूटीटी बैकएंड:**
|
||||
```python
|
||||
def map_topic(self, generic_topic: str) -> tuple[str, int]:
|
||||
# Parse: q1/tg/flow/text-completion-requests
|
||||
qos, tenant, namespace, queue = generic_topic.split('/', 3)
|
||||
|
||||
# Map QoS level
|
||||
qos_level = {'q0': 0, 'q1': 1, 'q2': 2}[qos]
|
||||
|
||||
# Build MQTT topic including tenant/namespace for proper namespacing
|
||||
mqtt_topic = f"{tenant}/{namespace}/{queue}"
|
||||
|
||||
return mqtt_topic, qos_level
|
||||
```
|
||||
|
||||
### अद्यतित विषय सहायक फ़ंक्शन
|
||||
|
||||
```python
|
||||
# schema/core/topic.py
|
||||
def topic(queue_name, qos='q1', tenant='tg', namespace='flow'):
|
||||
"""
|
||||
Create a generic topic identifier that can be mapped by backends.
|
||||
|
||||
Args:
|
||||
queue_name: The queue/topic name
|
||||
qos: Quality of service
|
||||
- 'q0' = best-effort (no ack)
|
||||
- 'q1' = at-least-once (ack required)
|
||||
- 'q2' = exactly-once (two-phase ack)
|
||||
tenant: Tenant identifier for multi-tenancy
|
||||
namespace: Namespace within tenant
|
||||
|
||||
Returns:
|
||||
Generic topic string: qos/tenant/namespace/queue_name
|
||||
|
||||
Examples:
|
||||
topic('my-queue') # q1/tg/flow/my-queue
|
||||
topic('config', qos='q2', namespace='config') # q2/tg/config/config
|
||||
"""
|
||||
return f"{qos}/{tenant}/{namespace}/{queue_name}"
|
||||
```
|
||||
|
||||
### कॉन्फ़िगरेशन और इनिशियलाइज़ेशन
|
||||
|
||||
**कमांड-लाइन तर्क + पर्यावरण चर:**
|
||||
|
||||
```python
|
||||
# In base/async_processor.py - add_args() method
|
||||
@staticmethod
|
||||
def add_args(parser):
|
||||
# Pub/sub backend selection
|
||||
parser.add_argument(
|
||||
'--pubsub-backend',
|
||||
default=os.getenv('PUBSUB_BACKEND', 'pulsar'),
|
||||
choices=['pulsar', 'mqtt'],
|
||||
help='Pub/sub backend (default: pulsar, env: PUBSUB_BACKEND)'
|
||||
)
|
||||
|
||||
# Pulsar-specific configuration
|
||||
parser.add_argument(
|
||||
'--pulsar-host',
|
||||
default=os.getenv('PULSAR_HOST', 'pulsar://localhost:6650'),
|
||||
help='Pulsar host (default: pulsar://localhost:6650, env: PULSAR_HOST)'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--pulsar-api-key',
|
||||
default=os.getenv('PULSAR_API_KEY', None),
|
||||
help='Pulsar API key (env: PULSAR_API_KEY)'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--pulsar-listener',
|
||||
default=os.getenv('PULSAR_LISTENER', None),
|
||||
help='Pulsar listener name (env: PULSAR_LISTENER)'
|
||||
)
|
||||
|
||||
# MQTT-specific configuration
|
||||
parser.add_argument(
|
||||
'--mqtt-host',
|
||||
default=os.getenv('MQTT_HOST', 'localhost'),
|
||||
help='MQTT broker host (default: localhost, env: MQTT_HOST)'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--mqtt-port',
|
||||
type=int,
|
||||
default=int(os.getenv('MQTT_PORT', '1883')),
|
||||
help='MQTT broker port (default: 1883, env: MQTT_PORT)'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--mqtt-username',
|
||||
default=os.getenv('MQTT_USERNAME', None),
|
||||
help='MQTT username (env: MQTT_USERNAME)'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--mqtt-password',
|
||||
default=os.getenv('MQTT_PASSWORD', None),
|
||||
help='MQTT password (env: MQTT_PASSWORD)'
|
||||
)
|
||||
```
|
||||
|
||||
**फ़ैक्टरी फ़ंक्शन:**
|
||||
|
||||
```python
|
||||
# In base/pubsub.py or base/pubsub_factory.py
|
||||
def get_pubsub(**config) -> PubSubBackend:
|
||||
"""
|
||||
Create and return a pub/sub backend based on configuration.
|
||||
|
||||
Args:
|
||||
config: Configuration dict from command-line args
|
||||
Must include 'pubsub_backend' key
|
||||
|
||||
Returns:
|
||||
Backend instance (PulsarBackend, MQTTBackend, etc.)
|
||||
"""
|
||||
backend_type = config.get('pubsub_backend', 'pulsar')
|
||||
|
||||
if backend_type == 'pulsar':
|
||||
return PulsarBackend(
|
||||
host=config.get('pulsar_host'),
|
||||
api_key=config.get('pulsar_api_key'),
|
||||
listener=config.get('pulsar_listener'),
|
||||
)
|
||||
elif backend_type == 'mqtt':
|
||||
return MQTTBackend(
|
||||
host=config.get('mqtt_host'),
|
||||
port=config.get('mqtt_port'),
|
||||
username=config.get('mqtt_username'),
|
||||
password=config.get('mqtt_password'),
|
||||
)
|
||||
else:
|
||||
raise ValueError(f"Unknown pub/sub backend: {backend_type}")
|
||||
```
|
||||
|
||||
**एसिंक्रोनसप्रोसेसर में उपयोग:**
|
||||
|
||||
```python
|
||||
# In async_processor.py
|
||||
class AsyncProcessor:
|
||||
def __init__(self, **params):
|
||||
self.id = params.get("id")
|
||||
|
||||
# Create backend from config (replaces PulsarClient)
|
||||
self.pubsub = get_pubsub(**params)
|
||||
|
||||
# Rest of initialization...
|
||||
```
|
||||
|
||||
### बैकएंड इंटरफ़ेस
|
||||
|
||||
```python
|
||||
class PubSubBackend(Protocol):
|
||||
"""Protocol defining the interface all pub/sub backends must implement."""
|
||||
|
||||
def create_producer(self, topic: str, schema: type, **options) -> BackendProducer:
|
||||
"""
|
||||
Create a producer for a topic.
|
||||
|
||||
Args:
|
||||
topic: Generic topic format (qos/tenant/namespace/queue)
|
||||
schema: Dataclass type for messages
|
||||
options: Backend-specific options (e.g., chunking_enabled)
|
||||
|
||||
Returns:
|
||||
Backend-specific producer instance
|
||||
"""
|
||||
...
|
||||
|
||||
def create_consumer(
|
||||
self,
|
||||
topic: str,
|
||||
subscription: str,
|
||||
schema: type,
|
||||
initial_position: str = 'latest',
|
||||
consumer_type: str = 'shared',
|
||||
**options
|
||||
) -> BackendConsumer:
|
||||
"""
|
||||
Create a consumer for a topic.
|
||||
|
||||
Args:
|
||||
topic: Generic topic format (qos/tenant/namespace/queue)
|
||||
subscription: Subscription/consumer group name
|
||||
schema: Dataclass type for messages
|
||||
initial_position: 'earliest' or 'latest' (MQTT may ignore)
|
||||
consumer_type: 'shared', 'exclusive', 'failover' (MQTT may ignore)
|
||||
options: Backend-specific options
|
||||
|
||||
Returns:
|
||||
Backend-specific consumer instance
|
||||
"""
|
||||
...
|
||||
|
||||
def close(self) -> None:
|
||||
"""Close the backend connection."""
|
||||
...
|
||||
```
|
||||
|
||||
```python
|
||||
class BackendProducer(Protocol):
|
||||
"""Protocol for backend-specific producer."""
|
||||
|
||||
def send(self, message: Any, properties: dict = {}) -> None:
|
||||
"""Send a message (dataclass instance) with optional properties."""
|
||||
...
|
||||
|
||||
def flush(self) -> None:
|
||||
"""Flush any buffered messages."""
|
||||
...
|
||||
|
||||
def close(self) -> None:
|
||||
"""Close the producer."""
|
||||
...
|
||||
```
|
||||
|
||||
```python
|
||||
class BackendConsumer(Protocol):
|
||||
"""Protocol for backend-specific consumer."""
|
||||
|
||||
def receive(self, timeout_millis: int = 2000) -> Message:
|
||||
"""
|
||||
Receive a message from the topic.
|
||||
|
||||
Raises:
|
||||
TimeoutError: If no message received within timeout
|
||||
"""
|
||||
...
|
||||
|
||||
def acknowledge(self, message: Message) -> None:
|
||||
"""Acknowledge successful processing of a message."""
|
||||
...
|
||||
|
||||
def negative_acknowledge(self, message: Message) -> None:
|
||||
"""Negative acknowledge - triggers redelivery."""
|
||||
...
|
||||
|
||||
def unsubscribe(self) -> None:
|
||||
"""Unsubscribe from the topic."""
|
||||
...
|
||||
|
||||
def close(self) -> None:
|
||||
"""Close the consumer."""
|
||||
...
|
||||
```
|
||||
|
||||
```python
|
||||
class Message(Protocol):
|
||||
"""Protocol for a received message."""
|
||||
|
||||
def value(self) -> Any:
|
||||
"""Get the deserialized message (dataclass instance)."""
|
||||
...
|
||||
|
||||
def properties(self) -> dict:
|
||||
"""Get message properties/metadata."""
|
||||
...
|
||||
```
|
||||
|
||||
### मौजूदा कक्षाओं का पुनर्गठन
|
||||
|
||||
मौजूदा `Consumer`, `Producer`, `Publisher`, `Subscriber` कक्षाएं काफी हद तक अपरिवर्तित रहेंगी:
|
||||
|
||||
**वर्तमान जिम्मेदारियां (बनाए रखें):**
|
||||
एसिंक्रोनस थ्रेडिंग मॉडल और टास्कग्रुप
|
||||
पुनः कनेक्शन लॉजिक और पुनः प्रयास प्रबंधन
|
||||
मेट्रिक्स संग्रह
|
||||
दर सीमित करना
|
||||
समवर्ती प्रबंधन
|
||||
|
||||
**आवश्यक परिवर्तन:**
|
||||
सीधे पल्सर आयात को हटा दें (`pulsar.schema`, `pulsar.InitialPosition`, आदि)
|
||||
पल्सर क्लाइंट के बजाय `BackendProducer`/`BackendConsumer` स्वीकार करें
|
||||
वास्तविक पब/सब संचालन को बैकएंड इंस्टेंस को सौंपें
|
||||
सामान्य अवधारणाओं को बैकएंड कॉल में मैप करें
|
||||
|
||||
**उदाहरण पुनर्गठन:**
|
||||
|
||||
```python
|
||||
# OLD - consumer.py
|
||||
class Consumer:
|
||||
def __init__(self, client, topic, subscriber, schema, ...):
|
||||
self.client = client # Direct Pulsar client
|
||||
# ...
|
||||
|
||||
async def consumer_run(self):
|
||||
# Uses pulsar.InitialPosition, pulsar.ConsumerType
|
||||
self.consumer = self.client.subscribe(
|
||||
topic=self.topic,
|
||||
schema=JsonSchema(self.schema),
|
||||
initial_position=pulsar.InitialPosition.Earliest,
|
||||
consumer_type=pulsar.ConsumerType.Shared,
|
||||
)
|
||||
|
||||
# NEW - consumer.py
|
||||
class Consumer:
|
||||
def __init__(self, backend_consumer, schema, ...):
|
||||
self.backend_consumer = backend_consumer # Backend-specific consumer
|
||||
self.schema = schema
|
||||
# ...
|
||||
|
||||
async def consumer_run(self):
|
||||
# Backend consumer already created with right settings
|
||||
# Just use it directly
|
||||
while self.running:
|
||||
msg = await asyncio.to_thread(
|
||||
self.backend_consumer.receive,
|
||||
timeout_millis=2000
|
||||
)
|
||||
await self.handle_message(msg)
|
||||
```
|
||||
|
||||
### बैकएंड-विशिष्ट व्यवहार
|
||||
|
||||
**पल्सर बैकएंड:**
|
||||
`q0` को `non-persistent://` में मैप करता है, `q1`/`q2` को `persistent://` में मैप करता है।
|
||||
सभी प्रकार के उपभोक्ताओं का समर्थन करता है (साझा, विशेष, फेलओवर)।
|
||||
प्रारंभिक स्थिति का समर्थन करता है (सबसे पहले/सबसे बाद में)।
|
||||
मूल संदेश स्वीकृति।
|
||||
स्कीमा रजिस्ट्री समर्थन।
|
||||
|
||||
**एमक्यूटीटी बैकएंड:**
|
||||
`q0`/`q1`/`q2` को एमक्यूटीटी क्यूओएस स्तर 0/1/2 में मैप करता है।
|
||||
नामस्थान के लिए टॉपिक पथ में किरायेदार/नेमस्पेस शामिल करता है।
|
||||
सदस्यता नामों से स्वचालित रूप से क्लाइंट आईडी उत्पन्न करता है।
|
||||
प्रारंभिक स्थिति को अनदेखा करता है (मूल एमक्यूटीटी में कोई संदेश इतिहास नहीं)।
|
||||
उपभोक्ता प्रकार को अनदेखा करता है (एमक्यूटीटी क्लाइंट आईडी, उपभोक्ता समूहों का उपयोग नहीं करता है)।
|
||||
सरल प्रकाशित/सदस्यता मॉडल।
|
||||
|
||||
### डिज़ाइन निर्णयों का सारांश
|
||||
|
||||
1. ✅ **सामान्य कतार नामकरण**: `qos/tenant/namespace/queue-name` प्रारूप।
|
||||
2. ✅ **कतार आईडी में क्यूओएस**: कतार परिभाषा द्वारा निर्धारित, कॉन्फ़िगरेशन द्वारा नहीं।
|
||||
3. ✅ **पुनः कनेक्शन**: उपभोक्ता/उत्पादक कक्षाओं द्वारा संभाला जाता है, बैकएंड द्वारा नहीं।
|
||||
4. ✅ **एमक्यूटीटी टॉपिक**: उचित नामस्थान के लिए किरायेदार/नेमस्पेस शामिल करें।
|
||||
5. ✅ **संदेश इतिहास**: एमक्यूटीटी `initial_position` पैरामीटर को अनदेखा करता है (भविष्य में सुधार)।
|
||||
6. ✅ **क्लाइंट आईडी**: एमक्यूटीटी बैकएंड सदस्यता नाम से स्वचालित रूप से उत्पन्न करता है।
|
||||
|
||||
### भविष्य के सुधार
|
||||
|
||||
**एमक्यूटीटी संदेश इतिहास:**
|
||||
वैकल्पिक दृढ़ता परत (जैसे, रिटेन्ड संदेश, बाहरी स्टोर) जोड़ा जा सकता है।
|
||||
यह `initial_position='earliest'` का समर्थन करने की अनुमति देगा।
|
||||
प्रारंभिक कार्यान्वयन के लिए आवश्यक नहीं है।
|
||||
1516
docs/tech-specs/hi/python-api-refactor.hi.md
Normal file
1516
docs/tech-specs/hi/python-api-refactor.hi.md
Normal file
File diff suppressed because it is too large
Load diff
271
docs/tech-specs/hi/query-time-explainability.hi.md
Normal file
271
docs/tech-specs/hi/query-time-explainability.hi.md
Normal file
|
|
@ -0,0 +1,271 @@
|
|||
---
|
||||
layout: default
|
||||
title: "क्वेरी-टाइम एक्सप्लेनेबिलिटी (Query-Time Explainability)"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# क्वेरी-टाइम एक्सप्लेनेबिलिटी (Query-Time Explainability)
|
||||
|
||||
> **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.
|
||||
|
||||
## स्थिति (Status)
|
||||
|
||||
कार्यान्वित (Implemented)
|
||||
|
||||
## अवलोकन (Overview)
|
||||
|
||||
यह विनिर्देश बताता है कि GraphRAG क्वेरी निष्पादन के दौरान एक्सप्लेनेबिलिटी डेटा को कैसे रिकॉर्ड और संचारित करता है। इसका लक्ष्य पूर्ण पता लगाने की क्षमता है: अंतिम उत्तर से लेकर चयनित किनारों तक और फिर स्रोत दस्तावेजों तक।
|
||||
|
||||
क्वेरी-टाइम एक्सप्लेनेबिलिटी यह कैप्चर करती है कि GraphRAG पाइपलाइन तर्क के दौरान क्या करती है। यह निष्कर्षण-समय के प्रमाण से जुड़ा है, जो रिकॉर्ड करता है कि ज्ञान ग्राफ तथ्यों की उत्पत्ति कहाँ से हुई।
|
||||
|
||||
## शब्दावली (Terminology)
|
||||
|
||||
| शब्द | परिभाषा |
|
||||
|------|------------|
|
||||
| **एक्सप्लेनेबिलिटी (Explainability)** | यह रिकॉर्ड है कि एक परिणाम कैसे प्राप्त किया गया |
|
||||
| **सेशन (Session)** | एक एकल GraphRAG क्वेरी निष्पादन |
|
||||
| **एज सिलेक्शन (Edge Selection)** | तर्क के साथ प्रासंगिक किनारों का LLM-संचालित चयन |
|
||||
| **प्रूवेनेंस चेन (Provenance Chain)** | किनारे → चंक → पृष्ठ → दस्तावेज़ से पथ |
|
||||
|
||||
## आर्किटेक्चर (Architecture)
|
||||
|
||||
### एक्सप्लेनेबिलिटी फ्लो (Explainability Flow)
|
||||
|
||||
```
|
||||
GraphRAG Query
|
||||
│
|
||||
├─► Session Activity
|
||||
│ └─► Query text, timestamp
|
||||
│
|
||||
├─► Retrieval Entity
|
||||
│ └─► All edges retrieved from subgraph
|
||||
│
|
||||
├─► Selection Entity
|
||||
│ └─► Selected edges with LLM reasoning
|
||||
│ └─► Each edge links to extraction provenance
|
||||
│
|
||||
└─► Answer Entity
|
||||
└─► Reference to synthesized response (in librarian)
|
||||
```
|
||||
|
||||
### दो-चरणीय ग्राफआरएजी पाइपलाइन
|
||||
|
||||
1. **एज चयन**: एलएलएम सबग्राफ से प्रासंगिक किनारों का चयन करता है, प्रत्येक के लिए तर्क प्रदान करता है।
|
||||
2. **संश्लेषण**: एलएलएम केवल चयनित किनारों से उत्तर उत्पन्न करता है।
|
||||
|
||||
यह अलगाव व्याख्यात्मकता को सक्षम बनाता है - हमें ठीक से पता है कि किन किनारों ने योगदान दिया।
|
||||
|
||||
### भंडारण
|
||||
|
||||
व्याख्यात्मकता ट्रिपल कॉन्फ़िगर करने योग्य संग्रह में संग्रहीत हैं (डिफ़ॉल्ट: `explainability`)।
|
||||
यह स्रोत संबंधों के लिए प्रोवी-ओ ऑन्टोलॉजी का उपयोग करता है।
|
||||
किनारे संदर्भों के लिए आरडीएफ-स्टार रीफिकेशन।
|
||||
उत्तर सामग्री लाइब्रेरियन सेवा में संग्रहीत है (इनलाइन नहीं - बहुत बड़ा)।
|
||||
|
||||
### वास्तविक समय स्ट्रीमिंग
|
||||
|
||||
व्याख्यात्मकता घटनाएँ क्लाइंट को क्वेरी निष्पादित होने के दौरान स्ट्रीम की जाती हैं:
|
||||
|
||||
1. सत्र बनाया गया → घटना उत्सर्जित।
|
||||
2. किनारे पुनर्प्राप्त किए गए → घटना उत्सर्जित।
|
||||
3. तर्क के साथ किनारे चुने गए → घटना उत्सर्जित।
|
||||
4. उत्तर संश्लेषित → घटना उत्सर्जित।
|
||||
|
||||
क्लाइंट को `explain_id` और `explain_collection` प्राप्त होते हैं ताकि पूर्ण विवरण प्राप्त किए जा सकें।
|
||||
|
||||
## यूआरआई संरचना
|
||||
|
||||
सभी यूआरआई `urn:trustgraph:` नेमस्पेस का उपयोग करते हैं जिसमें यूयूआईडी शामिल हैं:
|
||||
|
||||
| इकाई | यूआरआई पैटर्न |
|
||||
|--------|-------------|
|
||||
| सत्र | `urn:trustgraph:session:{uuid}` |
|
||||
| पुनर्प्राप्ति | `urn:trustgraph:prov:retrieval:{uuid}` |
|
||||
| चयन | `urn:trustgraph:prov:selection:{uuid}` |
|
||||
| उत्तर | `urn:trustgraph:prov:answer:{uuid}` |
|
||||
| किनारे का चयन | `urn:trustgraph:prov:edge:{uuid}:{index}` |
|
||||
|
||||
## आरडीएफ मॉडल (प्रोवी-ओ)
|
||||
|
||||
### सत्र गतिविधि
|
||||
|
||||
```turtle
|
||||
<session-uri> a prov:Activity ;
|
||||
rdfs:label "GraphRAG query session" ;
|
||||
prov:startedAtTime "2024-01-15T10:30:00Z" ;
|
||||
tg:query "What was the War on Terror?" .
|
||||
```
|
||||
|
||||
### पुनर्प्राप्ति इकाई
|
||||
|
||||
```turtle
|
||||
<retrieval-uri> a prov:Entity ;
|
||||
rdfs:label "Retrieved edges" ;
|
||||
prov:wasGeneratedBy <session-uri> ;
|
||||
tg:edgeCount 50 .
|
||||
```
|
||||
|
||||
### चयन इकाई
|
||||
|
||||
```turtle
|
||||
<selection-uri> a prov:Entity ;
|
||||
rdfs:label "Selected edges" ;
|
||||
prov:wasDerivedFrom <retrieval-uri> ;
|
||||
tg:selectedEdge <edge-sel-0> ;
|
||||
tg:selectedEdge <edge-sel-1> .
|
||||
|
||||
<edge-sel-0> tg:edge << <s> <p> <o> >> ;
|
||||
tg:reasoning "This edge establishes the key relationship..." .
|
||||
```
|
||||
|
||||
### उत्तर इकाई
|
||||
|
||||
```turtle
|
||||
<answer-uri> a prov:Entity ;
|
||||
rdfs:label "GraphRAG answer" ;
|
||||
prov:wasDerivedFrom <selection-uri> ;
|
||||
tg:document <urn:trustgraph:answer:{uuid}> .
|
||||
```
|
||||
|
||||
`tg:document` संदर्भ लाइब्रेरियन सेवा में संग्रहीत उत्तर को दर्शाता है।
|
||||
|
||||
## नेमस्पेस स्थिरांक
|
||||
|
||||
`trustgraph-base/trustgraph/provenance/namespaces.py` में परिभाषित:
|
||||
|
||||
| स्थिरांक | यूआरआई |
|
||||
|----------|-----|
|
||||
| `TG_QUERY` | `https://trustgraph.ai/ns/query` |
|
||||
| `TG_EDGE_COUNT` | `https://trustgraph.ai/ns/edgeCount` |
|
||||
| `TG_SELECTED_EDGE` | `https://trustgraph.ai/ns/selectedEdge` |
|
||||
| `TG_EDGE` | `https://trustgraph.ai/ns/edge` |
|
||||
| `TG_REASONING` | `https://trustgraph.ai/ns/reasoning` |
|
||||
| `TG_CONTENT` | `https://trustgraph.ai/ns/content` |
|
||||
| `TG_DOCUMENT` | `https://trustgraph.ai/ns/document` |
|
||||
|
||||
## GraphRagResponse स्कीमा
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class GraphRagResponse:
|
||||
error: Error | None = None
|
||||
response: str = ""
|
||||
end_of_stream: bool = False
|
||||
explain_id: str | None = None
|
||||
explain_collection: str | None = None
|
||||
message_type: str = "" # "chunk" or "explain"
|
||||
end_of_session: bool = False
|
||||
```
|
||||
|
||||
### संदेश प्रकार
|
||||
|
||||
| संदेश_प्रकार | उद्देश्य |
|
||||
|--------------|---------|
|
||||
| `chunk` | प्रतिक्रिया पाठ (स्ट्रीमिंग या अंतिम) |
|
||||
| `explain` | आईआरआई संदर्भ के साथ व्याख्यात्मक घटना |
|
||||
|
||||
### सत्र जीवनचक्र
|
||||
|
||||
1. कई `explain` संदेश (सत्र, पुनर्प्राप्ति, चयन, उत्तर)
|
||||
2. कई `chunk` संदेश (स्ट्रीमिंग प्रतिक्रिया)
|
||||
3. `end_of_session=True` के साथ अंतिम `chunk`
|
||||
|
||||
## एज चयन प्रारूप
|
||||
|
||||
एलएलएम चयनित किनारों के साथ JSONL लौटाता है:
|
||||
|
||||
```jsonl
|
||||
{"id": "edge-hash-1", "reasoning": "This edge shows the key relationship..."}
|
||||
{"id": "edge-hash-2", "reasoning": "Provides supporting evidence..."}
|
||||
```
|
||||
|
||||
`id`, `(labeled_s, labeled_p, labeled_o)` का एक हैश है, जिसकी गणना `edge_id()` द्वारा की जाती है।
|
||||
|
||||
## यूआरआई का संरक्षण
|
||||
|
||||
### समस्या
|
||||
|
||||
GraphRAG, एलएलएम को समझने योग्य लेबल प्रदर्शित करता है, लेकिन स्पष्टीकरण के लिए मूल यूआरआई की आवश्यकता होती है ताकि स्रोत का पता लगाया जा सके।
|
||||
|
||||
### समाधान
|
||||
|
||||
`get_labelgraph()` दोनों लौटाता है:
|
||||
`labeled_edges`: एलएलएम के लिए `(label_s, label_p, label_o)` की सूची
|
||||
`uri_map`: एक डिक्शनरी जो `edge_id(labels)` को `(uri_s, uri_p, uri_o)` से जोड़ती है।
|
||||
|
||||
जब व्याख्यात्मक डेटा संग्रहीत किया जाता है, तो `uri_map` से यूआरआई का उपयोग किया जाता है।
|
||||
|
||||
## उत्पत्ति अनुरेखण
|
||||
|
||||
### किनारे से स्रोत तक
|
||||
|
||||
चयनित किनारों को मूल दस्तावेजों तक वापस ट्रेस किया जा सकता है:
|
||||
|
||||
1. समाहित उपग्राफ के लिए क्वेरी करें: `?subgraph tg:contains <<s p o>>`
|
||||
2. मूल दस्तावेज़ तक `prov:wasDerivedFrom` श्रृंखला का पालन करें
|
||||
3. श्रृंखला में प्रत्येक चरण: खंड → पृष्ठ → दस्तावेज़
|
||||
|
||||
### कैसेंड्रा उद्धृत त्रिक समर्थन
|
||||
|
||||
कैसेंड्रा क्वेरी सेवा उद्धृत त्रिकों के मिलान का समर्थन करती है:
|
||||
|
||||
```python
|
||||
# In get_term_value():
|
||||
elif term.type == TRIPLE:
|
||||
return serialize_triple(term.triple)
|
||||
```
|
||||
|
||||
यह इस तरह के प्रश्नों को सक्षम करता है:
|
||||
```
|
||||
?subgraph tg:contains <<http://example.org/s http://example.org/p "value">>
|
||||
```
|
||||
|
||||
## कमांड लाइन इंटरफेस (CLI) का उपयोग
|
||||
|
||||
```bash
|
||||
tg-invoke-graph-rag --explainable -q "What was the War on Terror?"
|
||||
```
|
||||
|
||||
### आउटपुट प्रारूप
|
||||
|
||||
```
|
||||
[session] urn:trustgraph:session:abc123
|
||||
|
||||
[retrieval] urn:trustgraph:prov:retrieval:abc123
|
||||
|
||||
[selection] urn:trustgraph:prov:selection:abc123
|
||||
Selected 12 edge(s)
|
||||
Edge: (Guantanamo, definition, A detention facility...)
|
||||
Reason: Directly connects Guantanamo to the War on Terror
|
||||
Source: Chunk 1 → Page 2 → Beyond the Vigilant State
|
||||
|
||||
[answer] urn:trustgraph:prov:answer:abc123
|
||||
|
||||
Based on the provided knowledge statements...
|
||||
```
|
||||
|
||||
### विशेषताएं
|
||||
|
||||
क्वेरी के दौरान वास्तविक समय में व्याख्यात्मक घटनाएं।
|
||||
`rdfs:label` के माध्यम से एज घटकों के लिए लेबल समाधान।
|
||||
`prov:wasDerivedFrom` के माध्यम से स्रोत श्रृंखला का पता लगाना।
|
||||
बार-बार क्वेरी से बचने के लिए लेबल कैशिंग।
|
||||
|
||||
## कार्यान्वित फाइलें
|
||||
|
||||
| फ़ाइल | उद्देश्य |
|
||||
|------|---------|
|
||||
| `trustgraph-base/trustgraph/provenance/uris.py` | यूआरआई जनरेटर |
|
||||
| `trustgraph-base/trustgraph/provenance/namespaces.py` | आरडीएफ नेमस्पेस स्थिरांक |
|
||||
| `trustgraph-base/trustgraph/provenance/triples.py` | ट्रिपल बिल्डर |
|
||||
| `trustgraph-base/trustgraph/schema/services/retrieval.py` | GraphRagResponse स्कीमा |
|
||||
| `trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py` | यूआरआई संरक्षण के साथ मुख्य GraphRAG |
|
||||
| `trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py` | लाइब्रेरियन एकीकरण के साथ सेवा |
|
||||
| `trustgraph-flow/trustgraph/query/triples/cassandra/service.py` | उद्धृत ट्रिपल क्वेरी समर्थन |
|
||||
| `trustgraph-cli/trustgraph/cli/invoke_graph_rag.py` | व्याख्यात्मक प्रदर्शन के साथ सीएलआई |
|
||||
|
||||
## संदर्भ
|
||||
|
||||
PROV-O (डब्ल्यू3सी प्रोवेनेंस ऑन्टोलॉजी): https://www.w3.org/TR/prov-o/
|
||||
RDF-star: https://w3c.github.io/rdf-star/
|
||||
निष्कर्षण-समय प्रोवेनेंस: `docs/tech-specs/extraction-time-provenance.md`
|
||||
296
docs/tech-specs/hi/rag-streaming-support.hi.md
Normal file
296
docs/tech-specs/hi/rag-streaming-support.hi.md
Normal file
|
|
@ -0,0 +1,296 @@
|
|||
---
|
||||
layout: default
|
||||
title: "RAG स्ट्रीमिंग सपोर्ट तकनीकी विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# RAG स्ट्रीमिंग सपोर्ट तकनीकी विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह विनिर्देश ग्राफआरएजी और डॉक्यूमेंटआरएजी सेवाओं में स्ट्रीमिंग सपोर्ट जोड़ने का वर्णन करता है, जो नॉलेज ग्राफ और डॉक्यूमेंट रिट्रीवल क्वेरी के लिए वास्तविक समय में टोकन-दर-टोकन प्रतिक्रियाएं सक्षम करता है। यह एलएलएम टेक्स्ट-कंप्लीशन, प्रॉम्प्ट और एजेंट सेवाओं के लिए पहले से लागू किए गए मौजूदा स्ट्रीमिंग आर्किटेक्चर का विस्तार करता है।
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
**संगत स्ट्रीमिंग यूएक्स**: सभी ट्रस्टग्राफ सेवाओं में समान स्ट्रीमिंग अनुभव प्रदान करें।
|
||||
**न्यूनतम एपीआई परिवर्तन**: एक ही `streaming` फ़्लैग के साथ स्ट्रीमिंग सपोर्ट जोड़ें, स्थापित पैटर्न का पालन करें।
|
||||
**पिछड़ा संगतता**: मौजूदा गैर-स्ट्रीमिंग व्यवहार को डिफ़ॉल्ट के रूप में बनाए रखें।
|
||||
**मौजूदा बुनियादी ढांचे का पुन: उपयोग**: पहले से लागू प्रॉम्प्टक्लाइंट स्ट्रीमिंग का लाभ उठाएं।
|
||||
**गेटवे सपोर्ट**: क्लाइंट एप्लिकेशन के लिए वेबसॉकेट गेटवे के माध्यम से स्ट्रीमिंग सक्षम करें।
|
||||
|
||||
## पृष्ठभूमि
|
||||
|
||||
वर्तमान में लागू की गई स्ट्रीमिंग सेवाएं:
|
||||
**एलएलएम टेक्स्ट-कंप्लीशन सेवा**: चरण 1 - एलएलएम प्रदाताओं से स्ट्रीमिंग।
|
||||
**प्रॉम्प्ट सेवा**: चरण 2 - प्रॉम्प्ट टेम्प्लेट के माध्यम से स्ट्रीमिंग।
|
||||
**एजेंट सेवा**: चरण 3-4 - इंक्रीमेंटल थॉट/ऑब्जर्वेशन/एन्सर चंक्स के साथ रीएक्ट प्रतिक्रियाओं को स्ट्रीमिंग करना।
|
||||
|
||||
आरएजी सेवाओं के लिए वर्तमान सीमाएं:
|
||||
ग्राफआरएजी और डॉक्यूमेंटआरएजी केवल ब्लॉकिंग प्रतिक्रियाओं का समर्थन करते हैं।
|
||||
उपयोगकर्ताओं को किसी भी आउटपुट को देखने से पहले एलएलएम प्रतिक्रिया पूरी होने तक इंतजार करना होगा।
|
||||
नॉलेज ग्राफ या डॉक्यूमेंट क्वेरी से लंबी प्रतिक्रियाओं के लिए खराब यूएक्स।
|
||||
अन्य ट्रस्टग्राफ सेवाओं की तुलना में असंगत अनुभव।
|
||||
|
||||
यह विनिर्देश ग्राफआरएजी और डॉक्यूमेंटआरएजी में स्ट्रीमिंग सपोर्ट जोड़कर इन कमियों को दूर करता है। टोकन-दर-टोकन प्रतिक्रियाओं को सक्षम करके, ट्रस्टग्राफ:
|
||||
सभी क्वेरी प्रकारों में संगत स्ट्रीमिंग यूएक्स प्रदान कर सकता है।
|
||||
आरएजी क्वेरी के लिए कथित विलंबता को कम कर सकता है।
|
||||
लंबी अवधि की क्वेरी के लिए बेहतर प्रगति प्रतिक्रिया प्रदान कर सकता है।
|
||||
क्लाइंट एप्लिकेशन में वास्तविक समय प्रदर्शन का समर्थन कर सकता है।
|
||||
|
||||
## तकनीकी डिजाइन
|
||||
|
||||
### आर्किटेक्चर
|
||||
|
||||
आरएजी स्ट्रीमिंग कार्यान्वयन मौजूदा बुनियादी ढांचे का लाभ उठाता है:
|
||||
|
||||
1. **प्रॉम्प्टक्लाइंट स्ट्रीमिंग** (पहले से लागू)
|
||||
`kg_prompt()` और `document_prompt()` पहले से ही `streaming` और `chunk_callback` पैरामीटर स्वीकार करते हैं।
|
||||
ये आंतरिक रूप से स्ट्रीमिंग सपोर्ट के साथ `prompt()` को कॉल करते हैं।
|
||||
प्रॉम्प्टक्लाइंट में कोई बदलाव आवश्यक नहीं है।
|
||||
|
||||
मॉड्यूल: `trustgraph-base/trustgraph/base/prompt_client.py`
|
||||
|
||||
2. **ग्राफआरएजी सेवा** (स्ट्रीमिंग पैरामीटर पास-थ्रू की आवश्यकता है)
|
||||
`query()` विधि में `streaming` पैरामीटर जोड़ें।
|
||||
`prompt_client.kg_prompt()` और कॉलबैक को `prompt_client.kg_prompt()` में पास करें।
|
||||
ग्राफआरैग रिक्वेस्ट स्कीमा में `streaming` फ़ील्ड की आवश्यकता है।
|
||||
|
||||
मॉड्यूल:
|
||||
`trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py`
|
||||
`trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py` (प्रोसेसर)
|
||||
`trustgraph-base/trustgraph/schema/graph_rag.py` (रिक्वेस्ट स्कीमा)
|
||||
`trustgraph-flow/trustgraph/gateway/dispatch/graph_rag.py` (गेटवे)
|
||||
|
||||
3. **डॉक्यूमेंटआरएजी सेवा** (स्ट्रीमिंग पैरामीटर पास-थ्रू की आवश्यकता है)
|
||||
`query()` विधि में `streaming` पैरामीटर जोड़ें।
|
||||
`prompt_client.document_prompt()` और कॉलबैक को `prompt_client.document_prompt()` में पास करें।
|
||||
डॉक्यूमेंटआरैग रिक्वेस्ट स्कीमा में `streaming` फ़ील्ड की आवश्यकता है।
|
||||
|
||||
मॉड्यूल:
|
||||
`trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py`
|
||||
`trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` (प्रोसेसर)
|
||||
`trustgraph-base/trustgraph/schema/document_rag.py` (रिक्वेस्ट स्कीमा)
|
||||
`trustgraph-flow/trustgraph/gateway/dispatch/document_rag.py` (गेटवे)
|
||||
|
||||
### डेटा फ्लो
|
||||
|
||||
**गैर-स्ट्रीमिंग (वर्तमान)**:
|
||||
```
|
||||
Client → Gateway → RAG Service → PromptClient.kg_prompt(streaming=False)
|
||||
↓
|
||||
Prompt Service → LLM
|
||||
↓
|
||||
Complete response
|
||||
↓
|
||||
Client ← Gateway ← RAG Service ← Response
|
||||
```
|
||||
|
||||
**स्ट्रीमिंग (प्रस्तावित):**
|
||||
```
|
||||
Client → Gateway → RAG Service → PromptClient.kg_prompt(streaming=True, chunk_callback=cb)
|
||||
↓
|
||||
Prompt Service → LLM (streaming)
|
||||
↓
|
||||
Chunk → callback → RAG Response (chunk)
|
||||
↓ ↓
|
||||
Client ← Gateway ← ────────────────────────────────── Response stream
|
||||
```
|
||||
|
||||
### एपीआई (APIs)
|
||||
|
||||
**ग्राफआरएजी (GraphRAG) में बदलाव**:
|
||||
|
||||
1. **GraphRag.query()** - स्ट्रीमिंग पैरामीटर जोड़े गए।
|
||||
```python
|
||||
async def query(
|
||||
self, query, user, collection,
|
||||
verbose=False, streaming=False, chunk_callback=None # NEW
|
||||
):
|
||||
# ... existing entity/triple retrieval ...
|
||||
|
||||
if streaming and chunk_callback:
|
||||
resp = await self.prompt_client.kg_prompt(
|
||||
query, kg,
|
||||
streaming=True,
|
||||
chunk_callback=chunk_callback
|
||||
)
|
||||
else:
|
||||
resp = await self.prompt_client.kg_prompt(query, kg)
|
||||
|
||||
return resp
|
||||
```
|
||||
|
||||
2. **ग्राफराग रिक्वेस्ट स्कीमा** - स्ट्रीमिंग फ़ील्ड जोड़ें।
|
||||
```python
|
||||
class GraphRagRequest(Record):
|
||||
query = String()
|
||||
user = String()
|
||||
collection = String()
|
||||
streaming = Boolean() # NEW
|
||||
```
|
||||
|
||||
3. **ग्राफराग रिस्पांस स्कीमा** - स्ट्रीमिंग फ़ील्ड जोड़ें (एजेंट पैटर्न का पालन करें)।
|
||||
```python
|
||||
class GraphRagResponse(Record):
|
||||
response = String() # Legacy: complete response
|
||||
chunk = String() # NEW: streaming chunk
|
||||
end_of_stream = Boolean() # NEW: indicates last chunk
|
||||
```
|
||||
|
||||
4. **प्रोसेसर** - डेटा को लगातार प्रवाहित करें।
|
||||
```python
|
||||
async def handle(self, msg):
|
||||
# ... existing code ...
|
||||
|
||||
async def send_chunk(chunk):
|
||||
await self.respond(GraphRagResponse(
|
||||
chunk=chunk,
|
||||
end_of_stream=False,
|
||||
response=None
|
||||
))
|
||||
|
||||
if request.streaming:
|
||||
full_response = await self.rag.query(
|
||||
query=request.query,
|
||||
user=request.user,
|
||||
collection=request.collection,
|
||||
streaming=True,
|
||||
chunk_callback=send_chunk
|
||||
)
|
||||
# Send final message
|
||||
await self.respond(GraphRagResponse(
|
||||
chunk=None,
|
||||
end_of_stream=True,
|
||||
response=full_response
|
||||
))
|
||||
else:
|
||||
# Existing non-streaming path
|
||||
response = await self.rag.query(...)
|
||||
await self.respond(GraphRagResponse(response=response))
|
||||
```
|
||||
|
||||
**डॉक्यूमेंटआरएजी में परिवर्तन**:
|
||||
|
||||
ग्राफआरएजी के समान पैटर्न:
|
||||
1. `streaming` और `chunk_callback` पैरामीटर को `DocumentRag.query()` में जोड़ें।
|
||||
2. `streaming` फ़ील्ड को `DocumentRagRequest` में जोड़ें।
|
||||
3. `chunk` और `end_of_stream` फ़ील्ड को `DocumentRagResponse` में जोड़ें।
|
||||
4. प्रोसेसर को कॉलबैक के साथ स्ट्रीमिंग को संभालने के लिए अपडेट करें।
|
||||
|
||||
**गेटवे में परिवर्तन**:
|
||||
|
||||
गेटवे/डिस्पैच में `graph_rag.py` और `document_rag.py` दोनों को वेबसॉकेट पर स्ट्रीमिंग चंक्स को अग्रेषित करने के लिए अपडेट की आवश्यकता है:
|
||||
|
||||
```python
|
||||
async def handle(self, message, session, websocket):
|
||||
# ... existing code ...
|
||||
|
||||
if request.streaming:
|
||||
async def recipient(resp):
|
||||
if resp.chunk:
|
||||
await websocket.send(json.dumps({
|
||||
"id": message["id"],
|
||||
"response": {"chunk": resp.chunk},
|
||||
"complete": resp.end_of_stream
|
||||
}))
|
||||
return resp.end_of_stream
|
||||
|
||||
await self.rag_client.request(request, recipient=recipient)
|
||||
else:
|
||||
# Existing non-streaming path
|
||||
resp = await self.rag_client.request(request)
|
||||
await websocket.send(...)
|
||||
```
|
||||
|
||||
### कार्यान्वयन विवरण
|
||||
|
||||
**कार्यान्वयन क्रम**:
|
||||
1. स्कीमा फ़ील्ड जोड़ें (RAG सेवाओं दोनों के लिए अनुरोध + प्रतिक्रिया)
|
||||
2. GraphRag.query() और DocumentRag.query() विधियों को अपडेट करें
|
||||
3. प्रोसेसर को स्ट्रीमिंग को संभालने के लिए अपडेट करें
|
||||
4. गेटवे डिस्पैच हैंडलर को अपडेट करें
|
||||
5. `--no-streaming` ध्वज `tg-invoke-graph-rag` और `tg-invoke-document-rag` में जोड़ें (डिफ़ॉल्ट रूप से स्ट्रीमिंग सक्षम, एजेंट CLI पैटर्न का अनुसरण करते हुए)
|
||||
|
||||
**कॉलबैक पैटर्न**:
|
||||
एजेंट स्ट्रीमिंग में स्थापित समान एसिंक्रोनस कॉल बैक पैटर्न का पालन करें:
|
||||
प्रोसेसर `async def send_chunk(chunk)` कॉल बैक को परिभाषित करता है
|
||||
कॉल बैक को RAG सेवा को पास करता है
|
||||
RAG सेवा कॉल बैक को PromptClient को पास करती है
|
||||
PromptClient प्रत्येक LLM टुकड़े के लिए कॉल बैक को लागू करता है
|
||||
प्रोसेसर प्रत्येक टुकड़े के लिए स्ट्रीमिंग प्रतिक्रिया संदेश भेजता है
|
||||
|
||||
**त्रुटि प्रबंधन**:
|
||||
स्ट्रीमिंग के दौरान होने वाली त्रुटियों को `end_of_stream=True` के साथ त्रुटि प्रतिक्रिया भेजनी चाहिए
|
||||
एजेंट स्ट्रीमिंग से मौजूदा त्रुटि प्रसार पैटर्न का पालन करें
|
||||
|
||||
## सुरक्षा संबंधी विचार
|
||||
|
||||
मौजूदा RAG सेवाओं से परे कोई नया सुरक्षा संबंधी विचार नहीं:
|
||||
स्ट्रीमिंग प्रतिक्रियाएं समान उपयोगकर्ता/संग्रह अलगाव का उपयोग करती हैं
|
||||
प्रमाणीकरण या प्राधिकरण में कोई बदलाव नहीं
|
||||
टुकड़े की सीमाएं संवेदनशील डेटा को उजागर नहीं करती हैं
|
||||
|
||||
## प्रदर्शन संबंधी विचार
|
||||
|
||||
**लाभ**:
|
||||
कथित विलंबता में कमी (पहले टोकन तेजी से आते हैं)
|
||||
लंबे उत्तरों के लिए बेहतर UX
|
||||
कम मेमोरी उपयोग (पूरे उत्तर को बफर करने की आवश्यकता नहीं है)
|
||||
|
||||
**संभावित चिंताएं**:
|
||||
स्ट्रीमिंग प्रतिक्रियाओं के लिए अधिक Pulsar संदेश
|
||||
टुकड़ा करने/कॉल बैक ओवरहेड के लिए थोड़ा अधिक CPU
|
||||
स्ट्रीमिंग वैकल्पिक है, डिफ़ॉल्ट गैर-स्ट्रीमिंग रहता है, जिससे इसे कम किया जा सकता है
|
||||
|
||||
**परीक्षण संबंधी विचार**:
|
||||
बड़ी नॉलेज ग्राफ (कई त्रिगुण) के साथ परीक्षण करें
|
||||
कई पुनर्प्राप्त दस्तावेज़ों के साथ परीक्षण करें
|
||||
स्ट्रीमिंग बनाम गैर-स्ट्रीमिंग के ओवरहेड को मापें
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
**इकाई परीक्षण**:
|
||||
streaming=True/False के साथ GraphRag.query() का परीक्षण करें
|
||||
streaming=True/False के साथ DocumentRag.query() का परीक्षण करें
|
||||
कॉल बैक कार्यान्वयन को सत्यापित करने के लिए PromptClient को मॉक करें
|
||||
|
||||
**एकीकरण परीक्षण**:
|
||||
पूर्ण GraphRAG स्ट्रीमिंग प्रवाह का परीक्षण करें (मौजूदा एजेंट स्ट्रीमिंग परीक्षणों के समान)
|
||||
पूर्ण DocumentRAG स्ट्रीमिंग प्रवाह का परीक्षण करें
|
||||
गेटवे स्ट्रीमिंग अग्रेषण का परीक्षण करें
|
||||
CLI स्ट्रीमिंग आउटपुट का परीक्षण करें
|
||||
|
||||
**मैन्युअल परीक्षण**:
|
||||
`tg-invoke-graph-rag -q "What is machine learning?"` (डिफ़ॉल्ट रूप से स्ट्रीमिंग)
|
||||
`tg-invoke-document-rag -q "Summarize the documents about AI"` (डिफ़ॉल्ट रूप से स्ट्रीमिंग)
|
||||
`tg-invoke-graph-rag --no-streaming -q "..."` (गैर-स्ट्रीमिंग मोड का परीक्षण करें)
|
||||
सत्यापित करें कि स्ट्रीमिंग मोड में वृद्धिशील आउटपुट दिखाई दे रहा है
|
||||
|
||||
## माइग्रेशन योजना
|
||||
|
||||
माइग्रेशन की आवश्यकता नहीं:
|
||||
`streaming` पैरामीटर (डिफ़ॉल्ट रूप से False) के माध्यम से स्ट्रीमिंग वैकल्पिक है
|
||||
मौजूदा क्लाइंट अपरिवर्तित रहते हैं
|
||||
नए क्लाइंट स्ट्रीमिंग को अपना सकते हैं
|
||||
|
||||
## समयरेखा
|
||||
|
||||
अनुमानित कार्यान्वयन: 4-6 घंटे
|
||||
चरण 1 (2 घंटे): GraphRAG स्ट्रीमिंग समर्थन
|
||||
चरण 2 (2 घंटे): DocumentRAG स्ट्रीमिंग समर्थन
|
||||
चरण 3 (1-2 घंटे): गेटवे अपडेट और CLI ध्वज
|
||||
परीक्षण: प्रत्येक चरण में शामिल
|
||||
|
||||
## खुले प्रश्न
|
||||
|
||||
क्या हमें NLP क्वेरी सेवा में भी स्ट्रीमिंग समर्थन जोड़ना चाहिए?
|
||||
क्या हम केवल LLM आउटपुट या मध्यवर्ती चरणों (जैसे, "इकाइयों को पुनर्प्राप्त करना...", "ग्राफ को क्वेरी करना...") को स्ट्रीम करना चाहते हैं?
|
||||
क्या GraphRAG/DocumentRAG प्रतिक्रियाओं में टुकड़े मेटाडेटा (जैसे, टुकड़े संख्या, कुल अपेक्षित) शामिल होना चाहिए?
|
||||
|
||||
## संदर्भ
|
||||
|
||||
मौजूदा कार्यान्वयन: `docs/tech-specs/streaming-llm-responses.md`
|
||||
एजेंट स्ट्रीमिंग: `trustgraph-flow/trustgraph/agent/react/agent_manager.py`
|
||||
PromptClient स्ट्रीमिंग: `trustgraph-base/trustgraph/base/prompt_client.py`
|
||||
99
docs/tech-specs/hi/schema-refactoring-proposal.hi.md
Normal file
99
docs/tech-specs/hi/schema-refactoring-proposal.hi.md
Normal file
|
|
@ -0,0 +1,99 @@
|
|||
---
|
||||
layout: default
|
||||
title: "पहले"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
## स्कीमा निर्देशिका का पुनर्गठन प्रस्ताव
|
||||
|
||||
## वर्तमान मुद्दे
|
||||
|
||||
1. **सममित संरचना** - सभी स्कीमा एक ही निर्देशिका में होने से उनके बीच के संबंधों को समझना मुश्किल हो जाता है
|
||||
2. **विभिन्न चिंताएं** - कोर प्रकार, डोमेन ऑब्जेक्ट और एपीआई अनुबंध सभी एक साथ
|
||||
3. **अस्पष्ट नामकरण** - फ़ाइलें जैसे "object.py", "types.py", "topic.py" स्पष्ट रूप से उनकी propósito नहीं दर्शाती हैं
|
||||
4. **स्पष्ट परतें नहीं** - यह स्पष्ट नहीं है कि कौन सी चीज़ किससे जुड़ी है
|
||||
|
||||
## प्रस्तावित संरचना
|
||||
|
||||
```
|
||||
trustgraph-base/trustgraph/schema/
|
||||
├── __init__.py
|
||||
├── core/ # हर जगह उपयोग किए जाने वाले कोर मूल प्रकार
|
||||
│ ├── __init__.py
|
||||
│ ├── primitives.py # त्रुटि, मूल्य, त्रिक, फ़ील्ड, पंक्ति स्कीमा
|
||||
│ ├── metadata.py # मेटाडेटा रिकॉर्ड
|
||||
│ └── topic.py # विषय उपयोगिताएं
|
||||
│
|
||||
├── knowledge/ # ज्ञान डोमेन मॉडल और निष्कर्षण
|
||||
│ ├── __init__.py
|
||||
│ ├── graph.py # एंटिटीसंदर्भ, एंटिटी एम्बेडिंग, त्रिक
|
||||
│ ├── document.py # दस्तावेज़, टेक्स्टदस्तावेज़, टुकड़ा
|
||||
│ ├── knowledge.py # ज्ञान निष्कर्षण प्रकार
|
||||
│ ├── embeddings.py # सभी एम्बेडिंग संबंधित प्रकार (कई फ़ाइलों से स्थानांतरित)
|
||||
│ └── nlp.py # परिभाषा, विषय, संबंध, तथ्य प्रकार
|
||||
│
|
||||
└── services/ # सेवा अनुरोध/प्रतिक्रिया अनुबंध
|
||||
├── __init__.py
|
||||
├── llm.py # टेक्स्टकम्प्लीशन, एम्बेडिंग, टूल अनुरोध/प्रतिक्रिया
|
||||
├── retrieval.py # ग्राफ़RAG, दस्तावेज़RAG क्वेरी/प्रतिक्रिया
|
||||
├── query.py # ग्राफ़एम्बेडिंग अनुरोध/प्रतिक्रिया, दस्तावेज़एम्बेडिंग अनुरोध/प्रतिक्रिया
|
||||
├── agent.py # एजेंट अनुरोध/प्रतिक्रिया
|
||||
├── flow.py # फ़्लो अनुरोध/प्रतिक्रिया
|
||||
├── prompt.py # प्रॉम्प्ट सेवा अनुरोध/प्रतिक्रिया
|
||||
├── config.py # कॉन्फ़िगरेशन सेवा
|
||||
├── library.py # लाइब्रेरियन सेवा
|
||||
└── lookup.py # लुकअप सेवा
|
||||
```
|
||||
|
||||
## मुख्य परिवर्तन
|
||||
|
||||
1. **पदानुक्रमित संगठन** - स्पष्ट विभाजन कोर प्रकारों, ज्ञान मॉडल और सेवा अनुबंधों के बीच
|
||||
2. **बेहतर नामकरण**:
|
||||
- `types.py` → `core/primitives.py` (अधिक स्पष्ट उद्देश्य)
|
||||
- `object.py` → वास्तविक सामग्री के आधार पर उचित फ़ाइलों में विभाजित
|
||||
- `documents.py` → `knowledge/document.py` (एकल, सुसंगत)
|
||||
- `models.py` → `services/llm.py` (अधिक स्पष्ट रूप से किस प्रकार के मॉडल)
|
||||
- `prompt.py` → विभाजित: सेवा भागों को `services/prompt.py` में, डेटा प्रकारों को `knowledge/nlp.py` में
|
||||
|
||||
3. **तार्किक समूहीकरण**:
|
||||
- सभी एम्बेडिंग प्रकारों को `knowledge/embeddings.py` में समेकित किया गया है
|
||||
- सभी LLM-संबंधित सेवा अनुबंधों को `services/llm.py` में रखा गया है
|
||||
- सेवाओं की निर्देशिका में अनुरोध/प्रतिक्रिया जोड़े का स्पष्ट विभाजन
|
||||
- ज्ञान निष्कर्षण प्रकारों को अन्य ज्ञान डोमेन मॉडल के साथ समूहीकृत किया गया है
|
||||
|
||||
4. **निर्भरता स्पष्टता**:
|
||||
- कोर प्रकारों में कोई निर्भरता नहीं है
|
||||
- ज्ञान मॉडल केवल कोर पर निर्भर होते हैं
|
||||
- सेवा अनुबंध कोर और ज्ञान मॉडल दोनों पर निर्भर हो सकते हैं
|
||||
|
||||
## माइग्रेशन के लाभ
|
||||
|
||||
1. **आसान नेविगेशन** - डेवलपर्स आसानी से वह ढूंढ सकते हैं जिसकी उन्हें आवश्यकता है
|
||||
2. **बेहतर मॉड्यूलरिटी** - विभिन्न चिंताओं के बीच स्पष्ट सीमाएं
|
||||
3. **सरल आयात** - अधिक सहज आयात पथ
|
||||
4. **भविष्य के लिए तैयार** - बिना किसी अव्यवस्था के, नई ज्ञान प्रकारों या सेवाओं को आसानी से जोड़ा जा सकता है
|
||||
|
||||
## उदाहरण आयात परिवर्तन
|
||||
|
||||
```python
|
||||
# पहले
|
||||
|
||||
> **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.
|
||||
from trustgraph.schema import Error, Triple, GraphEmbeddings, TextCompletionRequest
|
||||
|
||||
# बाद में
|
||||
from trustgraph.schema.core import Error, Triple
|
||||
from trustgraph.schema.knowledge import GraphEmbeddings
|
||||
from trustgraph.schema.services import TextCompletionRequest
|
||||
```
|
||||
|
||||
## कार्यान्वयन नोट्स
|
||||
|
||||
1. मूल `__init__.py` में आयात को बनाए रखकर पिछड़े अनुकूलता बनाए रखें
|
||||
2. धीरे-धीरे फ़ाइलों को स्थानांतरित करें, आवश्यक अनुसार आयात को अपडेट करें
|
||||
3. एक `legacy.py` जोड़ने पर विचार करें जो एक संक्रमण अवधि के लिए सब कुछ आयात करता है
|
||||
4. नए संरचना को दर्शाने के लिए दस्तावेज़ अपडेट करें
|
||||
|
||||
<function_calls>
|
||||
<invoke name="TodoWrite">
|
||||
<parameter name="todos">[{"id": "1", "content": "वर्तमान स्कीमा निर्देशिका संरचना की जाँच करें", "status": "पूर्ण", "प्राथमिकता": "उच्च"}, {"id": "2", "content": "स्कीमा फ़ाइलों और उनके उद्देश्यों का विश्लेषण करें", "status": "पूर्ण", "प्राथमिकता": "उच्च"}, {"id": "3", "content": "बेहतर नामकरण और संरचना का प्रस्ताव", "status": "पूर्ण", "प्राथमिकता": "उच्च"}]
|
||||
578
docs/tech-specs/hi/streaming-llm-responses.hi.md
Normal file
578
docs/tech-specs/hi/streaming-llm-responses.hi.md
Normal file
|
|
@ -0,0 +1,578 @@
|
|||
---
|
||||
layout: default
|
||||
title: "स्ट्रीमिंग एलएलएम प्रतिक्रियाओं के लिए तकनीकी विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# स्ट्रीमिंग एलएलएम प्रतिक्रियाओं के लिए तकनीकी विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह विनिर्देश ट्रस्टग्राफ में एलएलएम प्रतिक्रियाओं के लिए स्ट्रीमिंग समर्थन के कार्यान्वयन का वर्णन करता है। स्ट्रीमिंग, उत्पन्न किए जा रहे टोकन को वास्तविक समय में वितरित करने की अनुमति देता है, बजाय कि पूरी प्रतिक्रिया उत्पन्न होने तक प्रतीक्षा करने के।
|
||||
स्ट्रीमिंग, एलएलएम द्वारा उत्पन्न किए जा रहे टोकन को वास्तविक समय में वितरित करने की अनुमति देता है, बजाय कि पूरी प्रतिक्रिया उत्पन्न होने तक प्रतीक्षा करने के।
|
||||
स्ट्रीमिंग, उत्पन्न किए जा रहे टोकन को वास्तविक समय में वितरित करने की अनुमति देता है, बजाय कि पूरी प्रतिक्रिया उत्पन्न होने तक प्रतीक्षा करने के।
|
||||
स्ट्रीमिंग, उत्पन्न किए जा रहे टोकन को वास्तविक समय में वितरित करने की अनुमति देता है, बजाय कि पूरी प्रतिक्रिया उत्पन्न होने तक प्रतीक्षा करने के।
|
||||
|
||||
यह कार्यान्वयन निम्नलिखित उपयोग मामलों का समर्थन करता है:
|
||||
|
||||
1. **वास्तविक समय उपयोगकर्ता इंटरफेस**: उत्पन्न होने पर टोकन को UI में भेजें,
|
||||
जिससे तत्काल दृश्य प्रतिक्रिया प्रदान की जा सके।
|
||||
2. **पहले टोकन के लिए कम समय**: उपयोगकर्ता तुरंत आउटपुट देखना शुरू करते हैं,
|
||||
पूर्ण पीढ़ी की प्रतीक्षा करने के बजाय।
|
||||
3. **लंबी प्रतिक्रिया प्रबंधन**: बहुत लंबी आउटपुट को संभालें जो अन्यथा
|
||||
समय समाप्त हो सकते हैं या मेमोरी सीमा से अधिक हो सकते हैं।
|
||||
4. **इंटरैक्टिव एप्लिकेशन**: उत्तरदायी चैट और एजेंट इंटरफेस को सक्षम करें।
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
**पिछड़ा संगतता (Backward Compatibility)**: मौजूदा, गैर-स्ट्रीमिंग क्लाइंट बिना किसी बदलाव के काम करते रहते हैं।
|
||||
बिना किसी बदलाव के।
|
||||
**संगत एपीआई डिज़ाइन (Consistent API Design)**: स्ट्रीमिंग और गैर-स्ट्रीमिंग दोनों समान स्कीमा पैटर्न का उपयोग करते हैं, जिसमें न्यूनतम विचलन होता है।
|
||||
होता है।
|
||||
**प्रदाता लचीलापन (Provider Flexibility)**: जहां उपलब्ध हो, वहां स्ट्रीमिंग का समर्थन करें, और जहां उपलब्ध न हो, वहां सुचारू रूप से वापस आएं।
|
||||
वापस आएं।
|
||||
**चरणबद्ध कार्यान्वयन (Phased Rollout)**: जोखिम को कम करने के लिए क्रमिक कार्यान्वयन।
|
||||
**एंड-टू-एंड समर्थन (End-to-End Support)**: एलएलएम प्रदाता से लेकर क्लाइंट तक स्ट्रीमिंग, पल्सर, गेटवे एपीआई और पायथन एपीआई के माध्यम से एप्लिकेशन तक।
|
||||
एप्लिकेशन तक।
|
||||
|
||||
## पृष्ठभूमि (Background)
|
||||
|
||||
### वर्तमान आर्किटेक्चर (Current Architecture)
|
||||
|
||||
वर्तमान एलएलएम टेक्स्ट कंप्लीशन प्रवाह इस प्रकार काम करता है:
|
||||
|
||||
1. क्लाइंट `TextCompletionRequest` भेजता है जिसमें `system` और `prompt` फ़ील्ड होते हैं।
|
||||
2. एलएलएम सेवा अनुरोध को संसाधित करती है और पूर्ण पीढ़ी की प्रतीक्षा करती है।
|
||||
3. पूर्ण `response` स्ट्रिंग के साथ एक `TextCompletionResponse` वापस किया जाता है।
|
||||
|
||||
वर्तमान स्कीमा (`trustgraph-base/trustgraph/schema/services/llm.py`):
|
||||
|
||||
```python
|
||||
class TextCompletionRequest(Record):
|
||||
system = String()
|
||||
prompt = String()
|
||||
|
||||
class TextCompletionResponse(Record):
|
||||
error = Error()
|
||||
response = String()
|
||||
in_token = Integer()
|
||||
out_token = Integer()
|
||||
model = String()
|
||||
```
|
||||
|
||||
### वर्तमान सीमाएँ
|
||||
|
||||
**विलंबता (Latency)**: उपयोगकर्ताओं को किसी भी आउटपुट को देखने से पहले पूर्ण पीढ़ी के पूरा होने का इंतजार करना पड़ता है।
|
||||
**समय-सीमा (Timeout) का जोखिम**: लंबी पीढ़ी क्लाइंट समय-सीमा सीमाओं से अधिक हो सकती है।
|
||||
**खराब उपयोगकर्ता अनुभव (Poor UX)**: पीढ़ी के दौरान कोई प्रतिक्रिया नहीं होने से धीमेपन का आभास होता है।
|
||||
**संसाधन उपयोग (Resource Usage)**: पूर्ण प्रतिक्रियाओं को मेमोरी में बफर किया जाना चाहिए।
|
||||
|
||||
यह विनिर्देश क्रमिक प्रतिक्रिया को सक्षम करके इन सीमाओं को संबोधित करता है, जबकि पूर्ण पश्च संगतता (backward compatibility) बनाए रखता है।
|
||||
|
||||
|
||||
## तकनीकी डिज़ाइन
|
||||
|
||||
### चरण 1: बुनियादी ढांचा
|
||||
|
||||
चरण 1, स्ट्रीमिंग के लिए आधार तैयार करता है, जिसमें स्कीमा, एपीआई और सीएलआई टूल में संशोधन शामिल हैं।
|
||||
|
||||
|
||||
#### स्कीमा परिवर्तन
|
||||
|
||||
##### एलएलएम स्कीमा (`trustgraph-base/trustgraph/schema/services/llm.py`)
|
||||
|
||||
**अनुरोध परिवर्तन:**
|
||||
|
||||
```python
|
||||
class TextCompletionRequest(Record):
|
||||
system = String()
|
||||
prompt = String()
|
||||
streaming = Boolean() # NEW: Default false for backward compatibility
|
||||
```
|
||||
|
||||
`streaming`: जब `true`, तो स्ट्रीमिंग प्रतिक्रिया डिलीवरी का अनुरोध करता है।
|
||||
डिफ़ॉल्ट: `false` (मौजूदा व्यवहार संरक्षित)।
|
||||
|
||||
**प्रतिक्रिया में परिवर्तन:**
|
||||
|
||||
```python
|
||||
class TextCompletionResponse(Record):
|
||||
error = Error()
|
||||
response = String()
|
||||
in_token = Integer()
|
||||
out_token = Integer()
|
||||
model = String()
|
||||
end_of_stream = Boolean() # NEW: Indicates final message
|
||||
```
|
||||
|
||||
`end_of_stream`: जब `true`, तो यह दर्शाता है कि यह अंतिम (या एकमात्र) प्रतिक्रिया है।
|
||||
गैर-स्ट्रीमिंग अनुरोधों के लिए: `end_of_stream=true` के साथ एकल प्रतिक्रिया।
|
||||
स्ट्रीमिंग अनुरोधों के लिए: `end_of_stream=false` के साथ कई प्रतिक्रियाएँ,
|
||||
अंतिम प्रतिक्रिया को छोड़कर।
|
||||
|
||||
##### प्रॉम्प्ट स्कीमा (`trustgraph-base/trustgraph/schema/services/prompt.py`)
|
||||
|
||||
प्रॉम्प्ट सेवा टेक्स्ट कंप्लीशन को लपेटती है, इसलिए यह समान पैटर्न को प्रतिबिंबित करती है:
|
||||
|
||||
**अनुरोध परिवर्तन:**
|
||||
|
||||
```python
|
||||
class PromptRequest(Record):
|
||||
id = String()
|
||||
terms = Map(String())
|
||||
streaming = Boolean() # NEW: Default false
|
||||
```
|
||||
|
||||
**प्रतिक्रिया में परिवर्तन:**
|
||||
|
||||
```python
|
||||
class PromptResponse(Record):
|
||||
error = Error()
|
||||
text = String()
|
||||
object = String()
|
||||
end_of_stream = Boolean() # NEW: Indicates final message
|
||||
```
|
||||
|
||||
#### गेटवे एपीआई में बदलाव
|
||||
|
||||
गेटवे एपीआई को एचटीटीपी/वेबसोकेट क्लाइंट्स के लिए स्ट्रीमिंग क्षमताएं प्रदान करनी होंगी।
|
||||
|
||||
**रेस्ट एपीआई अपडेट:**
|
||||
|
||||
`POST /api/v1/text-completion`: अनुरोध बॉडी में `streaming` पैरामीटर स्वीकार करें
|
||||
प्रतिक्रिया व्यवहार स्ट्रीमिंग फ़्लैग पर निर्भर करता है:
|
||||
`streaming=false`: एकल JSON प्रतिक्रिया (वर्तमान व्यवहार)
|
||||
`streaming=true`: सर्वर-सेंट इवेंट्स (एसएसई) स्ट्रीम या वेबसोकेट संदेश
|
||||
|
||||
**प्रतिक्रिया प्रारूप (स्ट्रीमिंग):**
|
||||
|
||||
प्रत्येक स्ट्रीम किए गए भाग में समान स्कीमा संरचना होती है:
|
||||
```json
|
||||
{
|
||||
"response": "partial text...",
|
||||
"end_of_stream": false,
|
||||
"model": "model-name"
|
||||
}
|
||||
```
|
||||
|
||||
अंतिम भाग:
|
||||
```json
|
||||
{
|
||||
"response": "final text chunk",
|
||||
"end_of_stream": true,
|
||||
"in_token": 150,
|
||||
"out_token": 500,
|
||||
"model": "model-name"
|
||||
}
|
||||
```
|
||||
|
||||
#### पायथन एपीआई में बदलाव
|
||||
|
||||
पायथन क्लाइंट एपीआई को स्ट्रीमिंग और नॉन-स्ट्रीमिंग दोनों मोड का समर्थन करना चाहिए
|
||||
साथ ही पिछली अनुकूलता बनाए रखनी चाहिए।
|
||||
|
||||
**LlmClient अपडेट** (`trustgraph-base/trustgraph/clients/llm_client.py`):
|
||||
|
||||
```python
|
||||
class LlmClient(BaseClient):
|
||||
def request(self, system, prompt, timeout=300, streaming=False):
|
||||
"""
|
||||
Non-streaming request (backward compatible).
|
||||
Returns complete response string.
|
||||
"""
|
||||
# Existing behavior when streaming=False
|
||||
|
||||
async def request_stream(self, system, prompt, timeout=300):
|
||||
"""
|
||||
Streaming request.
|
||||
Yields response chunks as they arrive.
|
||||
"""
|
||||
# New async generator method
|
||||
```
|
||||
|
||||
**प्रॉम्प्टक्लाइंट अपडेट** (`trustgraph-base/trustgraph/base/prompt_client.py`):
|
||||
|
||||
`streaming` पैरामीटर और एसिंक्रोनस जेनरेटर संस्करण के साथ समान पैटर्न।
|
||||
|
||||
#### सीएलआई टूल में बदलाव
|
||||
|
||||
**tg-invoke-llm** (`trustgraph-cli/trustgraph/cli/invoke_llm.py`):
|
||||
|
||||
```
|
||||
tg-invoke-llm [system] [prompt] [--no-streaming] [-u URL] [-f flow-id]
|
||||
```
|
||||
|
||||
डिफ़ॉल्ट रूप से बेहतर इंटरैक्टिव यूएक्स के लिए स्ट्रीमिंग सक्षम है।
|
||||
`--no-streaming` ध्वज स्ट्रीमिंग को अक्षम करता है।
|
||||
जब स्ट्रीमिंग हो: आउटपुट टोकन को stdout पर तब भेजें जब वे आएं।
|
||||
जब स्ट्रीमिंग न हो: पूर्ण प्रतिक्रिया की प्रतीक्षा करें, फिर आउटपुट करें।
|
||||
|
||||
**tg-invoke-prompt** (`trustgraph-cli/trustgraph/cli/invoke_prompt.py`):
|
||||
|
||||
```
|
||||
tg-invoke-prompt [template-id] [var=value...] [--no-streaming] [-u URL] [-f flow-id]
|
||||
```
|
||||
|
||||
`tg-invoke-llm` के समान पैटर्न।
|
||||
|
||||
#### एलएलएम सर्विस बेस क्लास में बदलाव
|
||||
|
||||
**LlmService** (`trustgraph-base/trustgraph/base/llm_service.py`):
|
||||
|
||||
```python
|
||||
class LlmService(FlowProcessor):
|
||||
async def on_request(self, msg, consumer, flow):
|
||||
request = msg.value()
|
||||
streaming = getattr(request, 'streaming', False)
|
||||
|
||||
if streaming and self.supports_streaming():
|
||||
async for chunk in self.generate_content_stream(...):
|
||||
await self.send_response(chunk, end_of_stream=False)
|
||||
await self.send_response(final_chunk, end_of_stream=True)
|
||||
else:
|
||||
response = await self.generate_content(...)
|
||||
await self.send_response(response, end_of_stream=True)
|
||||
|
||||
def supports_streaming(self):
|
||||
"""Override in subclass to indicate streaming support."""
|
||||
return False
|
||||
|
||||
async def generate_content_stream(self, system, prompt, model, temperature):
|
||||
"""Override in subclass to implement streaming."""
|
||||
raise NotImplementedError()
|
||||
```
|
||||
|
||||
--
|
||||
|
||||
### चरण 2: वर्टेक्सएआई प्रूफ ऑफ कॉन्सेप्ट
|
||||
|
||||
चरण 2, सत्यापन के लिए एक ही प्रदाता (वर्टेक्सएआई) में स्ट्रीमिंग को लागू करता है और एंड-टू-एंड परीक्षण को सक्षम करता है।
|
||||
बुनियादी ढांचे।
|
||||
|
||||
#### वर्टेक्सएआई कार्यान्वयन
|
||||
|
||||
**मॉड्यूल:** `trustgraph-vertexai/trustgraph/model/text_completion/vertexai/llm.py`
|
||||
|
||||
**परिवर्तन:**
|
||||
|
||||
1. `supports_streaming()` को `True` लौटाने के लिए ओवरराइड करें।
|
||||
2. `generate_content_stream()` एसिंक्रोनस जेनरेटर को लागू करें।
|
||||
3. जेमिनी और क्लाउड दोनों मॉडलों को संभालें (वर्टेक्सएआई एंथ्रोपिक एपीआई के माध्यम से)।
|
||||
|
||||
**जेमिनी स्ट्रीमिंग:**
|
||||
|
||||
```python
|
||||
async def generate_content_stream(self, system, prompt, model, temperature):
|
||||
model_instance = self.get_model(model, temperature)
|
||||
response = model_instance.generate_content(
|
||||
[system, prompt],
|
||||
stream=True # Enable streaming
|
||||
)
|
||||
for chunk in response:
|
||||
yield LlmChunk(
|
||||
text=chunk.text,
|
||||
in_token=None, # Available only in final chunk
|
||||
out_token=None,
|
||||
)
|
||||
# Final chunk includes token counts from response.usage_metadata
|
||||
```
|
||||
|
||||
**क्लाउड (वर्टेक्सएआई एंथ्रोपिक) स्ट्रीमिंग:**
|
||||
|
||||
```python
|
||||
async def generate_content_stream(self, system, prompt, model, temperature):
|
||||
with self.anthropic_client.messages.stream(...) as stream:
|
||||
for text in stream.text_stream:
|
||||
yield LlmChunk(text=text)
|
||||
# Token counts from stream.get_final_message()
|
||||
```
|
||||
|
||||
#### परीक्षण
|
||||
|
||||
स्ट्रीमिंग प्रतिक्रिया असेंबली के लिए यूनिट परीक्षण
|
||||
वर्टेक्सएआई (जेमिनी और क्लाउड) के साथ एकीकरण परीक्षण
|
||||
एंड-टू-एंड परीक्षण: CLI -> गेटवे -> पल्सर -> वर्टेक्सएआई -> बैक
|
||||
पिछड़े संगतता परीक्षण: गैर-स्ट्रीमिंग अनुरोध अभी भी काम करते हैं
|
||||
|
||||
--
|
||||
|
||||
### चरण 3: सभी एलएलएम प्रदाता
|
||||
|
||||
चरण 3 सिस्टम में सभी एलएलएम प्रदाताओं के लिए स्ट्रीमिंग समर्थन का विस्तार करता है।
|
||||
|
||||
#### प्रदाता कार्यान्वयन स्थिति
|
||||
|
||||
प्रत्येक प्रदाता को या तो:
|
||||
1. **पूर्ण स्ट्रीमिंग समर्थन**: `generate_content_stream()` को लागू करें
|
||||
2. **संगतता मोड**: `end_of_stream` ध्वज को सही ढंग से संभालें
|
||||
(एकल प्रतिक्रिया लौटाएं जिसमें `end_of_stream=true` हो)
|
||||
|
||||
| प्रदाता | पैकेज | स्ट्रीमिंग समर्थन |
|
||||
|----------|---------|-------------------|
|
||||
| ओपनएआई | trustgraph-flow | पूर्ण (मूल स्ट्रीमिंग एपीआई) |
|
||||
| क्लाउड/एंथ्रोपिक | trustgraph-flow | पूर्ण (मूल स्ट्रीमिंग एपीआई) |
|
||||
| ओलामा | trustgraph-flow | पूर्ण (मूल स्ट्रीमिंग एपीआई) |
|
||||
| कोहेर | trustgraph-flow | पूर्ण (मूल स्ट्रीमिंग एपीआई) |
|
||||
| मिस्ट्रल | trustgraph-flow | पूर्ण (मूल स्ट्रीमिंग एपीआई) |
|
||||
| एज़्योर ओपनएआई | trustgraph-flow | पूर्ण (मूल स्ट्रीमिंग एपीआई) |
|
||||
| गूगल एआई स्टूडियो | trustgraph-flow | पूर्ण (मूल स्ट्रीमिंग एपीआई) |
|
||||
| वर्टेक्सएआई | trustgraph-vertexai | पूर्ण (चरण 2) |
|
||||
| बेडरोक | trustgraph-bedrock | पूर्ण (मूल स्ट्रीमिंग एपीआई) |
|
||||
| एलएम स्टूडियो | trustgraph-flow | पूर्ण (ओपनएआई-संगत) |
|
||||
| लैमाफाइल | trustgraph-flow | पूर्ण (ओपनएआई-संगत) |
|
||||
| वीएलएलएम | trustgraph-flow | पूर्ण (ओपनएआई-संगत) |
|
||||
| टीजीआई | trustgraph-flow | तय किया जाना है |
|
||||
| एज़्योर | trustgraph-flow | तय किया जाना है |
|
||||
|
||||
#### कार्यान्वयन पैटर्न
|
||||
|
||||
ओपनएआई-संगत प्रदाताओं (ओपनएआई, एलएम स्टूडियो, लैमाफाइल, वीएलएलएम) के लिए:
|
||||
|
||||
```python
|
||||
async def generate_content_stream(self, system, prompt, model, temperature):
|
||||
response = await self.client.chat.completions.create(
|
||||
model=model,
|
||||
messages=[
|
||||
{"role": "system", "content": system},
|
||||
{"role": "user", "content": prompt}
|
||||
],
|
||||
temperature=temperature,
|
||||
stream=True
|
||||
)
|
||||
async for chunk in response:
|
||||
if chunk.choices[0].delta.content:
|
||||
yield LlmChunk(text=chunk.choices[0].delta.content)
|
||||
```
|
||||
|
||||
--
|
||||
|
||||
### चरण 4: एजेंट एपीआई
|
||||
|
||||
चरण 4, एजेंट एपीआई तक स्ट्रीमिंग का विस्तार करता है। यह अधिक जटिल है क्योंकि
|
||||
एजेंट एपीआई स्वभाव से ही मल्टी-मैसेज है (विचार → क्रिया → अवलोकन
|
||||
→ दोहराव → अंतिम उत्तर)।
|
||||
|
||||
#### वर्तमान एजेंट स्कीमा
|
||||
|
||||
```python
|
||||
class AgentStep(Record):
|
||||
thought = String()
|
||||
action = String()
|
||||
arguments = Map(String())
|
||||
observation = String()
|
||||
user = String()
|
||||
|
||||
class AgentRequest(Record):
|
||||
question = String()
|
||||
state = String()
|
||||
group = Array(String())
|
||||
history = Array(AgentStep())
|
||||
user = String()
|
||||
|
||||
class AgentResponse(Record):
|
||||
answer = String()
|
||||
error = Error()
|
||||
thought = String()
|
||||
observation = String()
|
||||
```
|
||||
|
||||
#### प्रस्तावित एजेंट स्कीमा में परिवर्तन
|
||||
|
||||
**परिवर्तन का अनुरोध:**
|
||||
|
||||
```python
|
||||
class AgentRequest(Record):
|
||||
question = String()
|
||||
state = String()
|
||||
group = Array(String())
|
||||
history = Array(AgentStep())
|
||||
user = String()
|
||||
streaming = Boolean() # NEW: Default false
|
||||
```
|
||||
|
||||
**प्रतिक्रिया में परिवर्तन:**
|
||||
|
||||
एजेंट अपनी तर्क प्रक्रिया के दौरान कई प्रकार के आउटपुट उत्पन्न करता है:
|
||||
विचार (तर्क)
|
||||
क्रियाएं (उपकरण कॉल)
|
||||
अवलोकन (उपकरण परिणाम)
|
||||
उत्तर (अंतिम प्रतिक्रिया)
|
||||
त्रुटियाँ
|
||||
|
||||
चूँकि `chunk_type` यह बताता है कि किस प्रकार की सामग्री भेजी जा रही है, इसलिए अलग-अलग
|
||||
`answer`, `error`, `thought`, और `observation` फ़ील्ड को एक साथ मिलाया जा सकता है।
|
||||
एक एकल `content` फ़ील्ड:
|
||||
|
||||
```python
|
||||
class AgentResponse(Record):
|
||||
chunk_type = String() # "thought", "action", "observation", "answer", "error"
|
||||
content = String() # The actual content (interpretation depends on chunk_type)
|
||||
end_of_message = Boolean() # Current thought/action/observation/answer is complete
|
||||
end_of_dialog = Boolean() # Entire agent dialog is complete
|
||||
```
|
||||
|
||||
**फ़ील्ड सिमेंटिक्स:**
|
||||
|
||||
`chunk_type`: यह इंगित करता है कि `content` फ़ील्ड में किस प्रकार की सामग्री है
|
||||
`"thought"`: एजेंट की तर्क/सोच
|
||||
`"action"`: उपयोग किए जा रहे टूल/क्रिया
|
||||
`"observation"`: टूल निष्पादन का परिणाम
|
||||
`"answer"`: उपयोगकर्ता के प्रश्न का अंतिम उत्तर
|
||||
`"error"`: त्रुटि संदेश
|
||||
|
||||
`content`: वास्तविक स्ट्रीम की सामग्री, जिसे `chunk_type` के आधार पर व्याख्यायित किया जाता है
|
||||
|
||||
`end_of_message`: जब `true`, तो वर्तमान चंक प्रकार पूरा हो गया है
|
||||
उदाहरण: वर्तमान विचार के लिए सभी टोकन भेजे जा चुके हैं
|
||||
यह क्लाइंट को यह जानने की अनुमति देता है कि अगले चरण पर कब जाना है
|
||||
|
||||
`end_of_dialog`: जब `true`, तो संपूर्ण एजेंट इंटरैक्शन पूरा हो गया है
|
||||
यह स्ट्रीम में अंतिम संदेश है
|
||||
|
||||
#### एजेंट स्ट्रीमिंग व्यवहार
|
||||
|
||||
जब `streaming=true`:
|
||||
|
||||
1. **विचार स्ट्रीमिंग:**
|
||||
`chunk_type="thought"`, `end_of_message=false` के साथ कई चंक
|
||||
अंतिम विचार चंक में `end_of_message=true` होता है
|
||||
2. **एक्शन नोटिफिकेशन:**
|
||||
`chunk_type="action"`, `end_of_message=true` के साथ एक चंक
|
||||
3. **अवलोकन:**
|
||||
`chunk_type="observation"` के साथ चंक(s), अंतिम में `end_of_message=true` होता है
|
||||
4. **चरण 1-3 को दोहराएं** क्योंकि एजेंट तर्क करता है
|
||||
5. **अंतिम उत्तर:**
|
||||
`chunk_type="answer"` जिसमें `content` में अंतिम प्रतिक्रिया है
|
||||
अंतिम चंक में `end_of_message=true`, `end_of_dialog=true` होता है
|
||||
|
||||
**उदाहरण स्ट्रीम अनुक्रम:**
|
||||
|
||||
```
|
||||
{chunk_type: "thought", content: "I need to", end_of_message: false, end_of_dialog: false}
|
||||
{chunk_type: "thought", content: " search for...", end_of_message: true, end_of_dialog: false}
|
||||
{chunk_type: "action", content: "search", end_of_message: true, end_of_dialog: false}
|
||||
{chunk_type: "observation", content: "Found: ...", end_of_message: true, end_of_dialog: false}
|
||||
{chunk_type: "thought", content: "Based on this", end_of_message: false, end_of_dialog: false}
|
||||
{chunk_type: "thought", content: " I can answer...", end_of_message: true, end_of_dialog: false}
|
||||
{chunk_type: "answer", content: "The answer is...", end_of_message: true, end_of_dialog: true}
|
||||
```
|
||||
|
||||
जब `streaming=false`:
|
||||
वर्तमान व्यवहार संरक्षित
|
||||
पूर्ण उत्तर के साथ एकल प्रतिक्रिया
|
||||
`end_of_message=true`, `end_of_dialog=true`
|
||||
|
||||
#### गेटवे और पायथन एपीआई
|
||||
|
||||
गेटवे: एजेंट स्ट्रीमिंग के लिए नया एसएसई/वेबसोकेट एंडपॉइंट
|
||||
पायथन एपीआई: नया `agent_stream()` एसिंक्रोनस जेनरेटर विधि
|
||||
|
||||
--
|
||||
|
||||
## सुरक्षा संबंधी विचार
|
||||
|
||||
**कोई नया आक्रमण सतह नहीं**: स्ट्रीमिंग समान प्रमाणीकरण/प्राधिकरण का उपयोग करती है
|
||||
**दर सीमा**: यदि आवश्यक हो तो प्रति-टोकन या प्रति-खंड दर सीमा लागू करें
|
||||
**कनेक्शन हैंडलिंग**: क्लाइंट डिस्कनेक्ट होने पर स्ट्रीम को ठीक से समाप्त करें
|
||||
**टाइमआउट प्रबंधन**: स्ट्रीमिंग अनुरोधों के लिए उचित टाइमआउट हैंडलिंग की आवश्यकता होती है
|
||||
|
||||
## प्रदर्शन संबंधी विचार
|
||||
|
||||
**मेमोरी**: स्ट्रीमिंग से पीक मेमोरी उपयोग कम होता है (कोई पूर्ण प्रतिक्रिया बफरिंग नहीं)
|
||||
**विलंबता**: पहले टोकन तक का समय काफी कम हो जाता है
|
||||
**कनेक्शन ओवरहेड**: एसएसई/वेबसोकेट कनेक्शन में कीप-अलाइव ओवरहेड होता है
|
||||
**पल्सर थ्रूपुट**: एक बड़े संदेश के मुकाबले कई छोटे संदेशों का व्यापार
|
||||
ट्रेडऑफ़
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
### यूनिट टेस्ट
|
||||
नए फ़ील्ड के साथ स्कीमा सीरियलाइज़ेशन/डीसेरियलाइज़ेशन
|
||||
पिछड़ा संगतता (गायब फ़ील्ड डिफ़ॉल्ट का उपयोग करते हैं)
|
||||
चंक असेंबली लॉजिक
|
||||
|
||||
### एकीकरण परीक्षण
|
||||
प्रत्येक एलएलएम प्रदाता का स्ट्रीमिंग कार्यान्वयन
|
||||
गेटवे एपीआई स्ट्रीमिंग एंडपॉइंट
|
||||
पायथन क्लाइंट स्ट्रीमिंग विधियाँ
|
||||
|
||||
### एंड-टू-एंड टेस्ट
|
||||
सीएलआई टूल स्ट्रीमिंग आउटपुट
|
||||
पूर्ण प्रवाह: क्लाइंट → गेटवे → पल्सर → एलएलएम → वापस
|
||||
मिश्रित स्ट्रीमिंग/गैर-स्ट्रीमिंग वर्कलोड
|
||||
|
||||
### पिछड़ा संगतता परीक्षण
|
||||
मौजूदा क्लाइंट बिना किसी संशोधन के काम करते हैं
|
||||
गैर-स्ट्रीमिंग अनुरोध समान रूप से व्यवहार करते हैं
|
||||
|
||||
## माइग्रेशन योजना
|
||||
|
||||
### चरण 1: बुनियादी ढांचा
|
||||
स्कीमा परिवर्तन तैनात करें (पिछड़ा संगत)
|
||||
गेटवे एपीआई अपडेट तैनात करें
|
||||
पायथन एपीआई अपडेट तैनात करें
|
||||
सीएलआई टूल अपडेट जारी करें
|
||||
|
||||
### चरण 2: वर्टेक्सएआई
|
||||
वर्टेक्सएआई स्ट्रीमिंग कार्यान्वयन को तैनात करें।
|
||||
परीक्षण वर्कलोड के साथ सत्यापन करें।
|
||||
|
||||
### चरण 3: सभी प्रदाता
|
||||
प्रदाता अपडेट को धीरे-धीरे लागू करें।
|
||||
समस्याओं की निगरानी करें।
|
||||
|
||||
### चरण 4: एजेंट एपीआई
|
||||
एजेंट स्कीमा परिवर्तनों को तैनात करें।
|
||||
एजेंट स्ट्रीमिंग कार्यान्वयन को तैनात करें।
|
||||
दस्तावेज़ को अपडेट करें।
|
||||
|
||||
## समयरेखा
|
||||
|
||||
| चरण | विवरण | निर्भरताएँ |
|
||||
|-------|-------------|--------------|
|
||||
| चरण 1 | बुनियादी ढांचा | कोई नहीं |
|
||||
| चरण 2 | वर्टेक्सएआई प्रूफ ऑफ कॉन्सेप्ट | चरण 1 |
|
||||
| चरण 3 | सभी प्रदाता | चरण 2 |
|
||||
| चरण 4 | एजेंट एपीआई | चरण 3 |
|
||||
|
||||
## डिज़ाइन निर्णय
|
||||
|
||||
निम्नलिखित प्रश्नों को विनिर्देश के दौरान हल किया गया था:
|
||||
|
||||
1. **स्ट्रीमिंग में टोकन गणना**: टोकन गणनाएँ अंतर हैं, न कि चल रही कुल।
|
||||
उपभोक्ता आवश्यकतानुसार उन्हें जोड़ सकते हैं। यह अधिकांश प्रदाता द्वारा उपयोग की रिपोर्टिंग के तरीके से मेल खाता है
|
||||
और कार्यान्वयन को सरल बनाता है।
|
||||
|
||||
2. **स्ट्रीम में त्रुटि प्रबंधन**: यदि कोई त्रुटि होती है, तो `error` फ़ील्ड भरा जाता है और अन्य फ़ील्ड की आवश्यकता नहीं होती है। त्रुटि हमेशा अंतिम संचार होती है - इसके बाद कोई अन्य संदेश अनुमत या अपेक्षित नहीं हैं।
|
||||
2. **स्ट्रीम में त्रुटि प्रबंधन**: यदि कोई त्रुटि होती है, तो ⟦CODE_0⟧ फ़ील्ड भरा जाता है और अन्य फ़ील्ड की आवश्यकता नहीं होती है। त्रुटि हमेशा अंतिम संचार होती है - इसके बाद कोई अन्य संदेश अनुमत या अपेक्षित नहीं हैं।
|
||||
2. **स्ट्रीम में त्रुटि प्रबंधन**: यदि कोई त्रुटि होती है, तो ⟦CODE_0⟧ फ़ील्ड भरा जाता है और अन्य फ़ील्ड की आवश्यकता नहीं होती है। त्रुटि हमेशा अंतिम संचार होती है - इसके बाद कोई अन्य संदेश अनुमत या अपेक्षित नहीं हैं।
|
||||
एक त्रुटि। एलएलएम/प्रॉम्प्ट स्ट्रीम के लिए, `end_of_stream=true`। एजेंट स्ट्रीम के लिए,
|
||||
`chunk_type="error"` को `end_of_dialog=true` के साथ।
|
||||
|
||||
3. **आंशिक प्रतिक्रिया पुनर्प्राप्ति**: संदेश प्रोटोकॉल (पल्सर) मजबूत है,
|
||||
इसलिए संदेश-स्तर पर पुनः प्रयास की आवश्यकता नहीं है। यदि कोई क्लाइंट स्ट्रीम को खो देता है
|
||||
या डिस्कनेक्ट हो जाता है, तो उसे पूरी अनुरोध को शुरुआत से फिर से प्रयास करना होगा।
|
||||
|
||||
4. **त्वरित सेवा स्ट्रीमिंग**: स्ट्रीमिंग केवल टेक्स्ट (`text`) के लिए समर्थित है।
|
||||
प्रतिक्रियाओं के लिए, संरचित (`object`) प्रतिक्रियाओं के लिए नहीं। त्वरित सेवा पहले से ही जानती है कि
|
||||
आउटपुट JSON होगा या टेक्स्ट-आधारित, यह प्रॉम्प्ट टेम्पलेट पर निर्भर करता है। यदि JSON-आउटपुट प्रॉम्प्ट के लिए
|
||||
एक स्ट्रीमिंग अनुरोध किया जाता है, तो
|
||||
सेवा को या तो:
|
||||
`end_of_stream=true` के साथ एक ही प्रतिक्रिया में पूरा JSON वापस करना चाहिए, या
|
||||
त्रुटि के साथ स्ट्रीमिंग अनुरोध को अस्वीकार करना चाहिए
|
||||
|
||||
## खुले प्रश्न
|
||||
|
||||
फिलहाल कोई नहीं।
|
||||
|
||||
## संदर्भ
|
||||
|
||||
वर्तमान एलएलएम स्कीमा: `trustgraph-base/trustgraph/schema/services/llm.py`
|
||||
वर्तमान प्रॉम्प्ट स्कीमा: `trustgraph-base/trustgraph/schema/services/prompt.py`
|
||||
वर्तमान एजेंट स्कीमा: `trustgraph-base/trustgraph/schema/services/agent.py`
|
||||
एलएलएम सेवा आधार: `trustgraph-base/trustgraph/base/llm_service.py`
|
||||
वर्टेक्सएआई प्रदाता: `trustgraph-vertexai/trustgraph/model/text_completion/vertexai/llm.py`
|
||||
गेटवे एपीआई: `trustgraph-base/trustgraph/api/`
|
||||
सीएलआई उपकरण: `trustgraph-cli/trustgraph/cli/`
|
||||
621
docs/tech-specs/hi/structured-data-2.hi.md
Normal file
621
docs/tech-specs/hi/structured-data-2.hi.md
Normal file
|
|
@ -0,0 +1,621 @@
|
|||
---
|
||||
layout: default
|
||||
title: "संरचित डेटा तकनीकी विनिर्देश (भाग 2)"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# संरचित डेटा तकनीकी विनिर्देश (भाग 2)
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह विनिर्देश उन मुद्दों और कमियों को संबोधित करता है जिन्हें ट्रस्टग्राफ के संरचित डेटा एकीकरण के प्रारंभिक कार्यान्वयन के दौरान पहचाना गया था, जैसा कि `structured-data.md` में वर्णित है।
|
||||
|
||||
## समस्या विवरण
|
||||
|
||||
### 1. नामकरण में असंगति: "ऑब्जेक्ट" बनाम "पंक्ति"
|
||||
|
||||
वर्तमान कार्यान्वयन में पूरे समय "ऑब्जेक्ट" शब्दावली का उपयोग किया जाता है (उदाहरण के लिए, `ExtractedObject`, ऑब्जेक्ट निष्कर्षण, ऑब्जेक्ट एम्बेडिंग)। यह नामकरण बहुत सामान्य है और भ्रम पैदा करता है:
|
||||
|
||||
"ऑब्जेक्ट" सॉफ्टवेयर में एक अतिव्यापी शब्द है (पायथन ऑब्जेक्ट, JSON ऑब्जेक्ट, आदि)।
|
||||
संसाधित डेटा अनिवार्य रूप से सारणीबद्ध है - परिभाषित स्कीमा वाली तालिकाओं में पंक्तियाँ।
|
||||
"पंक्ति" डेटा मॉडल का अधिक सटीक वर्णन है और यह डेटाबेस शब्दावली के साथ मेल खाता है।
|
||||
|
||||
यह असंगति मॉड्यूल नामों, क्लास नामों, संदेश प्रकारों और दस्तावेज़ों में दिखाई देती है।
|
||||
|
||||
### 2. पंक्ति भंडारण क्वेरी सीमाएँ
|
||||
|
||||
वर्तमान पंक्ति भंडारण कार्यान्वयन में महत्वपूर्ण क्वेरी सीमाएँ हैं:
|
||||
|
||||
**प्राकृतिक भाषा बेमेल**: क्वेरी वास्तविक दुनिया के डेटा विविधताओं के साथ संघर्ष करती हैं। उदाहरण के लिए:
|
||||
`"CHESTNUT ST"` युक्त एक सड़क डेटाबेस को `"Chestnut Street"` के बारे में पूछने पर खोजना मुश्किल है।
|
||||
संक्षिप्त नाम, केस अंतर और स्वरूपण भिन्नताएं सटीक-मेल क्वेरी को तोड़ देती हैं।
|
||||
उपयोगकर्ताओं को सिमेंटिक समझ की उम्मीद होती है, लेकिन स्टोर शाब्दिक मिलान प्रदान करता है।
|
||||
|
||||
**स्कीमा विकास मुद्दे**: स्कीमा में परिवर्तन समस्याएं पैदा करते हैं:
|
||||
मौजूदा डेटा अद्यतन स्कीमा के अनुरूप नहीं हो सकता है।
|
||||
तालिका संरचना में परिवर्तन क्वेरी और डेटा अखंडता को तोड़ सकते हैं।
|
||||
स्कीमा अपडेट के लिए कोई स्पष्ट माइग्रेशन पथ नहीं है।
|
||||
|
||||
### 3. पंक्ति एम्बेडिंग की आवश्यकता
|
||||
|
||||
समस्या 2 से संबंधित, सिस्टम को पंक्ति डेटा के लिए वेक्टर एम्बेडिंग की आवश्यकता है ताकि:
|
||||
|
||||
संरचित डेटा में सिमेंटिक खोज (जब डेटा में "CHESTNUT ST" हो तो "Chestnut Street" खोजना)।
|
||||
धुंधली क्वेरी के लिए समानता मिलान।
|
||||
संरचित फ़िल्टर को सिमेंटिक समानता के साथ मिलाने वाली हाइब्रिड खोज।
|
||||
बेहतर प्राकृतिक भाषा क्वेरी समर्थन।
|
||||
|
||||
एम्बेडिंग सेवा को निर्दिष्ट किया गया था लेकिन लागू नहीं किया गया था।
|
||||
|
||||
### 4. पंक्ति डेटा अंतर्ग्रहण अधूरा
|
||||
|
||||
संरचित डेटा अंतर्ग्रहण पाइपलाइन पूरी तरह से कार्यात्मक नहीं है:
|
||||
|
||||
इनपुट प्रारूपों (CSV, JSON, आदि) को वर्गीकृत करने के लिए नैदानिक संकेत मौजूद हैं।
|
||||
इन संकेतों का उपयोग करने वाली अंतर्ग्रहण सेवा को सिस्टम में प्लंब नहीं किया गया है।
|
||||
पंक्ति स्टोर में पूर्व-संरचित डेटा लोड करने के लिए कोई एंड-टू-एंड पथ नहीं है।
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
**स्कीमा लचीलापन**: मौजूदा डेटा को तोड़ने या माइग्रेशन की आवश्यकता के बिना स्कीमा विकास को सक्षम करें।
|
||||
**संगत नामकरण**: पूरे कोडबेस में "पंक्ति" शब्दावली का मानकीकरण करें।
|
||||
**सिमेंटिक क्वेरी क्षमता**: पंक्ति एम्बेडिंग के माध्यम से धुंधली/सिमेंटिक मिलान का समर्थन करें।
|
||||
**पूर्ण अंतर्ग्रहण पाइपलाइन**: संरचित डेटा लोड करने के लिए एंड-टू-एंड पथ प्रदान करें।
|
||||
|
||||
## तकनीकी डिजाइन
|
||||
|
||||
### एकीकृत पंक्ति भंडारण स्कीमा
|
||||
|
||||
पिछले कार्यान्वयन में प्रत्येक स्कीमा के लिए एक अलग कैसेंड्रा तालिका बनाई गई थी। इससे तब समस्याएं हुईं जब स्कीमा विकसित हुए, क्योंकि तालिका संरचना में परिवर्तन के लिए माइग्रेशन की आवश्यकता होती थी।
|
||||
|
||||
नए डिज़ाइन में सभी पंक्ति डेटा के लिए एक एकल, एकीकृत तालिका का उपयोग किया जाता है:
|
||||
|
||||
```sql
|
||||
CREATE TABLE rows (
|
||||
collection text,
|
||||
schema_name text,
|
||||
index_name text,
|
||||
index_value frozen<list<text>>,
|
||||
data map<text, text>,
|
||||
source text,
|
||||
PRIMARY KEY ((collection, schema_name, index_name), index_value)
|
||||
)
|
||||
```
|
||||
|
||||
#### कॉलम परिभाषाएँ
|
||||
|
||||
| कॉलम | प्रकार | विवरण |
|
||||
|--------|------|-------------|
|
||||
| `collection` | `text` | डेटा संग्रह/आयात पहचानकर्ता (मेटाडेटा से) |
|
||||
| `schema_name` | `text` | स्कीमा का नाम जिससे यह पंक्ति मेल खाती है |
|
||||
| `index_name` | `text` | अनुक्रमित फ़ील्ड का नाम, संयुक्त अल्पविराम के साथ (मिश्रित के लिए) |
|
||||
| `index_value` | `frozen<list<text>>` | अनुक्रमित मानों की सूची |
|
||||
| `data` | `map<text, text>` | पंक्ति डेटा कुंजी-मान जोड़े के रूप में |
|
||||
| `source` | `text` | वैकल्पिक यूआरआई जो नॉलेज ग्राफ में मूल जानकारी से लिंक करता है। खाली स्ट्रिंग या NULL इंगित करता है कि कोई स्रोत नहीं है। |
|
||||
|
||||
#### अनुक्रमण प्रबंधन
|
||||
|
||||
प्रत्येक पंक्ति कई बार संग्रहीत की जाती है - स्कीमा में परिभाषित प्रत्येक अनुक्रमित फ़ील्ड के लिए एक बार। प्राथमिक कुंजी फ़ील्ड को किसी विशेष मार्कर के बिना एक अनुक्रमणिका के रूप में माना जाता है, जो भविष्य में लचीलापन प्रदान करता है।
|
||||
|
||||
**सिंगल-फ़ील्ड अनुक्रमणिका का उदाहरण:**
|
||||
स्कीमा `email` को अनुक्रमित के रूप में परिभाषित करता है
|
||||
`index_name = "email"`
|
||||
`index_value = ['foo@bar.com']`
|
||||
|
||||
**मिश्रित अनुक्रमणिका का उदाहरण:**
|
||||
स्कीमा `region` और `status` पर मिश्रित अनुक्रमणिका को परिभाषित करता है
|
||||
`index_name = "region,status"` (फ़ील्ड नाम क्रमबद्ध और अल्पविराम से जुड़े हुए)
|
||||
`index_value = ['US', 'active']` (फ़ील्ड नामों के समान क्रम में मान)
|
||||
|
||||
**प्राथमिक कुंजी का उदाहरण:**
|
||||
स्कीमा `customer_id` को प्राथमिक कुंजी के रूप में परिभाषित करता है
|
||||
`index_name = "customer_id"`
|
||||
`index_value = ['CUST001']`
|
||||
|
||||
#### क्वेरी पैटर्न
|
||||
|
||||
सभी क्वेरी एक ही पैटर्न का पालन करती हैं, चाहे कोई भी अनुक्रमणिका उपयोग की जाए:
|
||||
|
||||
```sql
|
||||
SELECT * FROM rows
|
||||
WHERE collection = 'import_2024'
|
||||
AND schema_name = 'customers'
|
||||
AND index_name = 'email'
|
||||
AND index_value = ['foo@bar.com']
|
||||
```
|
||||
|
||||
#### डिज़ाइन में संतुलन
|
||||
|
||||
**लाभ:**
|
||||
स्कीमा में बदलावों के लिए टेबल संरचना में बदलाव की आवश्यकता नहीं होती है।
|
||||
पंक्ति डेटा कैसेंड्रा के लिए अस्पष्ट है - फ़ील्ड जोड़ने/हटाने से कोई फर्क नहीं पड़ता।
|
||||
सभी एक्सेस विधियों के लिए सुसंगत क्वेरी पैटर्न।
|
||||
कोई कैसेंड्रा सेकेंडरी इंडेक्स नहीं (जो बड़े पैमाने पर धीमे हो सकते हैं)।
|
||||
पूरी तरह से देशी कैसेंड्रा प्रकार (`map`, `frozen<list>`)।
|
||||
|
||||
**गड़बड़ियाँ:**
|
||||
राइट एम्प्लीफिकेशन: प्रत्येक पंक्ति डालने = N डालने (प्रत्येक इंडेक्स्ड फ़ील्ड के लिए एक)।
|
||||
डुप्लिकेट पंक्ति डेटा के कारण स्टोरेज ओवरहेड।
|
||||
प्रकार की जानकारी स्कीमा कॉन्फ़िगरेशन में संग्रहीत है, एप्लिकेशन लेयर पर रूपांतरण।
|
||||
|
||||
#### संगति मॉडल
|
||||
|
||||
डिज़ाइन कुछ सरलीकरणों को स्वीकार करता है:
|
||||
|
||||
1. **कोई पंक्ति अपडेट नहीं**: सिस्टम केवल अपेंड-ओनली है। यह एक ही पंक्ति की कई प्रतियों को अपडेट करने के बारे में संगति संबंधी चिंताओं को समाप्त करता है।
|
||||
|
||||
2. **स्कीमा परिवर्तन सहिष्णुता**: जब स्कीमा बदलते हैं (उदाहरण के लिए, इंडेक्स जोड़े/हटाए जाते हैं), तो मौजूदा पंक्तियाँ अपनी मूल इंडेक्सिंग को बनाए रखती हैं। पुराने पंक्तियों को नए इंडेक्स के माध्यम से खोजा नहीं जा सकता है। यदि आवश्यक हो, तो उपयोगकर्ता संगति सुनिश्चित करने के लिए एक स्कीमा को हटा और पुनः बना सकते हैं।
|
||||
|
||||
### विभाजन ट्रैकिंग और हटाना
|
||||
|
||||
#### समस्या
|
||||
|
||||
विभाजन कुंजी `(collection, schema_name, index_name)` के साथ, कुशल हटाने के लिए सभी विभाजन कुंजियों को हटाने की आवश्यकता होती है। केवल `collection` या `collection + schema_name` द्वारा हटाना उन सभी `index_name` मानों को जानने की आवश्यकता होती है जिनमें डेटा है।
|
||||
|
||||
#### विभाजन ट्रैकिंग टेबल
|
||||
|
||||
एक सेकेंडरी लुकअप टेबल ट्रैक करती है कि कौन से विभाजन मौजूद हैं:
|
||||
|
||||
```sql
|
||||
CREATE TABLE row_partitions (
|
||||
collection text,
|
||||
schema_name text,
|
||||
index_name text,
|
||||
PRIMARY KEY ((collection), schema_name, index_name)
|
||||
)
|
||||
```
|
||||
|
||||
यह हटाने के कार्यों के लिए विभाजनों की कुशल खोज को सक्षम बनाता है।
|
||||
|
||||
#### पंक्ति लेखक व्यवहार
|
||||
|
||||
पंक्ति लेखक पंजीकृत `(collection, schema_name)` युग्मों का एक इन-मेमोरी कैश बनाए रखता है। पंक्ति को संसाधित करते समय:
|
||||
|
||||
1. जांचें कि `(collection, schema_name)` कैश में है या नहीं।
|
||||
2. यदि कैश में नहीं है (इस युग्म के लिए पहली पंक्ति):
|
||||
सभी इंडेक्स नामों को प्राप्त करने के लिए स्कीमा कॉन्फ़िगरेशन देखें।
|
||||
प्रत्येक `(collection, schema_name, index_name)` के लिए `row_partitions` में प्रविष्टियाँ डालें।
|
||||
युग्म को कैश में जोड़ें।
|
||||
3. पंक्ति डेटा लिखने के साथ आगे बढ़ें।
|
||||
|
||||
पंक्ति लेखक स्कीमा कॉन्फ़िगरेशन परिवर्तन घटनाओं की भी निगरानी करता है। जब कोई स्कीमा बदलता है, तो प्रासंगिक कैश प्रविष्टियाँ साफ़ कर दी जाती हैं ताकि अगली पंक्ति अपडेट किए गए इंडेक्स नामों के साथ पुनः पंजीकरण को ट्रिगर करे।
|
||||
|
||||
इस दृष्टिकोण से यह सुनिश्चित होता है:
|
||||
लुकअप तालिका लेखन प्रत्येक `(collection, schema_name)` युग्म के लिए एक बार होता है, प्रत्येक पंक्ति के लिए नहीं।
|
||||
लुकअप तालिका उन इंडेक्स को दर्शाती है जो डेटा लिखे जाने पर सक्रिय थे।
|
||||
आयात के दौरान होने वाले स्कीमा परिवर्तनों को सही ढंग से पहचाना जाता है।
|
||||
|
||||
#### हटाने के कार्य
|
||||
|
||||
**संग्रह हटाएं:**
|
||||
```sql
|
||||
-- 1. Discover all partitions
|
||||
SELECT schema_name, index_name FROM row_partitions WHERE collection = 'X';
|
||||
|
||||
-- 2. Delete each partition from rows table
|
||||
DELETE FROM rows WHERE collection = 'X' AND schema_name = '...' AND index_name = '...';
|
||||
-- (repeat for each discovered partition)
|
||||
|
||||
-- 3. Clean up the lookup table
|
||||
DELETE FROM row_partitions WHERE collection = 'X';
|
||||
```
|
||||
|
||||
**संग्रह और स्कीमा हटाएं:**
|
||||
```sql
|
||||
-- 1. Discover partitions for this schema
|
||||
SELECT index_name FROM row_partitions WHERE collection = 'X' AND schema_name = 'Y';
|
||||
|
||||
-- 2. Delete each partition from rows table
|
||||
DELETE FROM rows WHERE collection = 'X' AND schema_name = 'Y' AND index_name = '...';
|
||||
-- (repeat for each discovered partition)
|
||||
|
||||
-- 3. Clean up the lookup table entries
|
||||
DELETE FROM row_partitions WHERE collection = 'X' AND schema_name = 'Y';
|
||||
```
|
||||
|
||||
### पंक्ति एम्बेडिंग
|
||||
|
||||
पंक्ति एम्बेडिंग, अनुक्रमित मानों पर अर्थपूर्ण/अस्पष्ट मिलान को सक्षम करते हैं, जिससे प्राकृतिक भाषा में विसंगति की समस्या हल होती है (उदाहरण के लिए, "चेस्टनट स्ट्रीट" के लिए खोज करते समय "चेस्टनट एसटी" खोजना)।
|
||||
|
||||
#### डिज़ाइन अवलोकन
|
||||
|
||||
प्रत्येक अनुक्रमित मान को एम्बेड किया जाता है और एक वेक्टर स्टोर (क्यूड्रेंट) में संग्रहीत किया जाता है। क्वेरी के समय, क्वेरी को एम्बेड किया जाता है, समान वेक्टर पाए जाते हैं, और संबंधित मेटाडेटा का उपयोग कैसेंड्रा में वास्तविक पंक्तियों को देखने के लिए किया जाता है।
|
||||
|
||||
#### क्यूड्रेंट संग्रह संरचना
|
||||
|
||||
प्रत्येक `(user, collection, schema_name, dimension)` टपल के लिए एक क्यूड्रेंट संग्रह:
|
||||
|
||||
**संग्रह नामकरण:** `rows_{user}_{collection}_{schema_name}_{dimension}`
|
||||
नामों को साफ़ किया जाता है (गैर-अक्षरांकीय वर्णों को `_` से बदला जाता है, लोअरकेस किया जाता है, संख्यात्मक उपसर्गों को `r_` उपसर्ग मिलता है)
|
||||
**तर्क:** एक `(user, collection, schema_name)` उदाहरण को मिलान वाले क्यूड्रेंट संग्रहों को हटाकर साफ-सुथरे तरीके से हटाने की अनुमति देता है; आयाम प्रत्यय विभिन्न एम्बेडिंग मॉडल को एक साथ मौजूद रहने की अनुमति देता है।
|
||||
|
||||
#### क्या एम्बेड किया जाता है
|
||||
|
||||
अनुक्रमण मानों का पाठ प्रतिनिधित्व:
|
||||
|
||||
| अनुक्रमण प्रकार | उदाहरण `index_value` | एम्बेड करने के लिए पाठ |
|
||||
|------------|----------------------|---------------|
|
||||
| एकल-क्षेत्र | `['foo@bar.com']` | `"foo@bar.com"` |
|
||||
| समग्र | `['US', 'active']` | `"US active"` (स्पेस-जोड़ा हुआ) |
|
||||
|
||||
#### बिंदु संरचना
|
||||
|
||||
प्रत्येक क्यूड्रेंट बिंदु में शामिल हैं:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "<uuid>",
|
||||
"vector": [0.1, 0.2, ...],
|
||||
"payload": {
|
||||
"index_name": "street_name",
|
||||
"index_value": ["CHESTNUT ST"],
|
||||
"text": "CHESTNUT ST"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| पेलोड फ़ील्ड | विवरण |
|
||||
|---------------|-------------|
|
||||
| `index_name` | यह एम्बेडिंग किस अनुक्रमित फ़ील्ड(s) का प्रतिनिधित्व करता है |
|
||||
| `index_value` | मूल्यों की मूल सूची (कैसेंड्रा लुकअप के लिए) |
|
||||
| `text` | वह पाठ जिसे एम्बेड किया गया था (डीबगिंग/प्रदर्शन के लिए) |
|
||||
|
||||
ध्यान दें: `user`, `collection`, और `schema_name` Qdrant संग्रह नाम से निहित हैं।
|
||||
|
||||
#### क्वेरी प्रवाह
|
||||
|
||||
1. उपयोगकर्ता U, संग्रह X, स्कीमा Y के भीतर "चेस्टनट स्ट्रीट" के लिए क्वेरी करता है।
|
||||
2. क्वेरी टेक्स्ट को एम्बेड करें।
|
||||
3. उपसर्ग `rows_U_X_Y_` से मेल खाने वाले Qdrant संग्रह नाम(s) निर्धारित करें।
|
||||
4. निकटतम वैक्टरों के लिए मिलान करने वाले Qdrant संग्रह(s) की खोज करें।
|
||||
5. `index_name` और `index_value` युक्त पेलोड वाले मिलान करने वाले बिंदुओं को प्राप्त करें।
|
||||
6. कैसेंड्रा को क्वेरी करें:
|
||||
```sql
|
||||
SELECT * FROM rows
|
||||
WHERE collection = 'X'
|
||||
AND schema_name = 'Y'
|
||||
AND index_name = '<from payload>'
|
||||
AND index_value = <from payload>
|
||||
```
|
||||
7. मिलान किए गए पंक्तियों को वापस करना
|
||||
|
||||
#### वैकल्पिक: इंडेक्स नाम द्वारा फ़िल्टरिंग
|
||||
|
||||
क्वेरी वैकल्पिक रूप से Qdrant में `index_name` द्वारा फ़िल्टर की जा सकती हैं ताकि केवल विशिष्ट फ़ील्ड की खोज की जा सके:
|
||||
|
||||
**"उन सभी फ़ील्ड को खोजें जो 'Chestnut' से मेल खाते हैं"** → संग्रह में सभी वैक्टर की खोज करें
|
||||
**"उन सड़कों को खोजें जिनका नाम 'Chestnut' से मेल खाता है"** → उन पंक्तियों को फ़िल्टर करें जहाँ `payload.index_name = 'street_name'`
|
||||
|
||||
#### आर्किटेक्चर
|
||||
|
||||
पंक्ति एम्बेडिंग **दो-चरणीय पैटर्न** का पालन करते हैं जिसका उपयोग GraphRAG (ग्राफ-एम्बेडिंग, दस्तावेज़-एम्बेडिंग) द्वारा किया जाता है:
|
||||
|
||||
**चरण 1: एम्बेडिंग गणना** (`trustgraph-flow/trustgraph/embeddings/row_embeddings/`) - `ExtractedObject` का उपयोग करता है, एम्बेडिंग सेवा के माध्यम से एम्बेडिंग की गणना करता है, `RowEmbeddings` आउटपुट करता है
|
||||
**चरण 2: एम्बेडिंग भंडारण** (`trustgraph-flow/trustgraph/storage/row_embeddings/qdrant/`) - `RowEmbeddings` का उपयोग करता है, वैक्टर को Qdrant में लिखता है
|
||||
|
||||
कैसेंड्रा पंक्ति लेखक एक अलग समानांतर उपभोक्ता है:
|
||||
|
||||
**कैसेंड्रा पंक्ति लेखक** (`trustgraph-flow/trustgraph/storage/rows/cassandra`) - `ExtractedObject` का उपयोग करता है, पंक्तियों को कैसेंड्रा में लिखता है
|
||||
|
||||
तीनों सेवाएं एक ही प्रवाह से डेटा लेती हैं, जिससे वे अलग-अलग रहती हैं। यह अनुमति देता है:
|
||||
कैसेंड्रा लेखन बनाम एम्बेडिंग पीढ़ी बनाम वेक्टर भंडारण का स्वतंत्र स्केलिंग
|
||||
यदि आवश्यक न हो तो एम्बेडिंग सेवाओं को अक्षम किया जा सकता है
|
||||
एक सेवा में विफलता अन्य सेवाओं को प्रभावित नहीं करती है
|
||||
GraphRAG पाइपलाइनों के साथ सुसंगत आर्किटेक्चर
|
||||
|
||||
#### लेखन पथ
|
||||
|
||||
**चरण 1 (पंक्ति-एम्बेडिंग प्रोसेसर):** जब एक `ExtractedObject` प्राप्त होता है:
|
||||
|
||||
1. अनुक्रमित फ़ील्ड खोजने के लिए स्कीमा देखें
|
||||
2. प्रत्येक अनुक्रमित फ़ील्ड के लिए:
|
||||
अनुक्रमण मान का पाठ प्रतिनिधित्व बनाएं
|
||||
एम्बेडिंग सेवा के माध्यम से एम्बेडिंग की गणना करें
|
||||
3. सभी गणना किए गए वैक्टर युक्त एक `RowEmbeddings` संदेश आउटपुट करें
|
||||
|
||||
**चरण 2 (पंक्ति-एम्बेडिंग-लिखें-Qdrant):** जब एक `RowEmbeddings` प्राप्त होता है:
|
||||
|
||||
1. संदेश में प्रत्येक एम्बेडिंग के लिए:
|
||||
`(user, collection, schema_name, dimension)` से Qdrant संग्रह निर्धारित करें
|
||||
यदि आवश्यक हो तो संग्रह बनाएं (पहली बार लिखने पर आलसी निर्माण)
|
||||
वेक्टर और पेलोड के साथ पॉइंट अपサート करें
|
||||
|
||||
#### संदेश प्रकार
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class RowIndexEmbedding:
|
||||
index_name: str # The indexed field name(s)
|
||||
index_value: list[str] # The field value(s)
|
||||
text: str # Text that was embedded
|
||||
vectors: list[list[float]] # Computed embedding vectors
|
||||
|
||||
@dataclass
|
||||
class RowEmbeddings:
|
||||
metadata: Metadata
|
||||
schema_name: str
|
||||
embeddings: list[RowIndexEmbedding]
|
||||
```
|
||||
|
||||
#### विलोपन एकीकरण
|
||||
|
||||
Qdrant संग्रह, संग्रह नाम पैटर्न पर उपसर्ग मिलान द्वारा खोजे जाते हैं:
|
||||
|
||||
**`(user, collection)` हटाएं:**
|
||||
1. `rows_{user}_{collection}_` उपसर्ग से मेल खाने वाले सभी Qdrant संग्रहों की सूची बनाएं
|
||||
2. प्रत्येक मेल खाने वाले संग्रह को हटाएं
|
||||
3. कैसेंड्रा पंक्तियों के विभाजन को हटाएं (जैसा कि ऊपर प्रलेखित है)
|
||||
4. `row_partitions` प्रविष्टियों को साफ़ करें
|
||||
|
||||
**`(user, collection, schema_name)` हटाएं:**
|
||||
1. `rows_{user}_{collection}_{schema_name}_` उपसर्ग से मेल खाने वाले सभी Qdrant संग्रहों की सूची बनाएं
|
||||
2. प्रत्येक मेल खाने वाले संग्रह को हटाएं (यह कई आयामों को संभालता है)
|
||||
3. कैसेंड्रा पंक्तियों के विभाजन को हटाएं
|
||||
4. `row_partitions` को साफ़ करें
|
||||
|
||||
#### मॉड्यूल स्थान
|
||||
|
||||
| चरण | मॉड्यूल | प्रवेश बिंदु |
|
||||
|-------|--------|-------------|
|
||||
| चरण 1 | `trustgraph-flow/trustgraph/embeddings/row_embeddings/` | `row-embeddings` |
|
||||
| चरण 2 | `trustgraph-flow/trustgraph/storage/row_embeddings/qdrant/` | `row-embeddings-write-qdrant` |
|
||||
|
||||
### पंक्ति एम्बेडिंग क्वेरी एपीआई
|
||||
|
||||
पंक्ति एम्बेडिंग क्वेरी, GraphQL पंक्ति क्वेरी सेवा से एक **अलग एपीआई** है:
|
||||
|
||||
| एपीआई | उद्देश्य | बैकएंड |
|
||||
|-----|---------|---------|
|
||||
| पंक्ति क्वेरी (GraphQL) | अनुक्रमित फ़ील्ड पर सटीक मिलान | कैसेंड्रा |
|
||||
| पंक्ति एम्बेडिंग क्वेरी | अस्पष्ट/अर्थ संबंधी मिलान | Qdrant |
|
||||
|
||||
यह अलगाव चिंताओं को साफ रखता है:
|
||||
GraphQL सेवा सटीक, संरचित प्रश्नों पर केंद्रित है
|
||||
एम्बेडिंग एपीआई अर्थ संबंधी समानता को संभालता है
|
||||
उपयोगकर्ता कार्यप्रवाह: उम्मीदवारों को खोजने के लिए एम्बेडिंग के माध्यम से अस्पष्ट खोज, फिर पूर्ण पंक्ति डेटा प्राप्त करने के लिए सटीक क्वेरी
|
||||
|
||||
#### अनुरोध/प्रतिक्रिया स्कीमा
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class RowEmbeddingsRequest:
|
||||
vectors: list[list[float]] # Query vectors (pre-computed embeddings)
|
||||
user: str = ""
|
||||
collection: str = ""
|
||||
schema_name: str = ""
|
||||
index_name: str = "" # Optional: filter to specific index
|
||||
limit: int = 10 # Max results per vector
|
||||
|
||||
@dataclass
|
||||
class RowIndexMatch:
|
||||
index_name: str = "" # The matched index field(s)
|
||||
index_value: list[str] = [] # The matched value(s)
|
||||
text: str = "" # Original text that was embedded
|
||||
score: float = 0.0 # Similarity score
|
||||
|
||||
@dataclass
|
||||
class RowEmbeddingsResponse:
|
||||
error: Error | None = None
|
||||
matches: list[RowIndexMatch] = []
|
||||
```
|
||||
|
||||
#### क्वेरी प्रोसेसर
|
||||
|
||||
मॉड्यूल: `trustgraph-flow/trustgraph/query/row_embeddings/qdrant`
|
||||
|
||||
प्रवेश बिंदु: `row-embeddings-query-qdrant`
|
||||
|
||||
प्रोसेसर:
|
||||
1. `RowEmbeddingsRequest` के साथ क्वेरी वेक्टर प्राप्त करता है
|
||||
2. उपसर्ग मिलान के माध्यम से उपयुक्त Qdrant संग्रह ढूंढता है
|
||||
3. वैकल्पिक `index_name` फ़िल्टर के साथ निकटतम वेक्टर खोजता है
|
||||
4. मिलान किए गए इंडेक्स जानकारी के साथ `RowEmbeddingsResponse` लौटाता है
|
||||
|
||||
#### एपीआई गेटवे एकीकरण
|
||||
|
||||
गेटवे मानक अनुरोध/प्रतिक्रिया पैटर्न के माध्यम से पंक्ति एम्बेडिंग प्रश्नों को उजागर करता है:
|
||||
|
||||
| घटक | स्थान |
|
||||
|-----------|----------|
|
||||
| डिस्पैचर | `trustgraph-flow/trustgraph/gateway/dispatch/row_embeddings_query.py` |
|
||||
| पंजीकरण | `"row-embeddings"` को `request_response_dispatchers` में `manager.py` में जोड़ें |
|
||||
|
||||
फ्लो इंटरफ़ेस नाम: `row-embeddings`
|
||||
|
||||
फ्लो ब्लूप्रिंट में इंटरफ़ेस परिभाषा:
|
||||
```json
|
||||
{
|
||||
"interfaces": {
|
||||
"row-embeddings": {
|
||||
"request": "non-persistent://tg/request/row-embeddings:{id}",
|
||||
"response": "non-persistent://tg/response/row-embeddings:{id}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### पायथन एसडीके समर्थन
|
||||
|
||||
एसडीके पंक्ति एम्बेडिंग प्रश्नों के लिए विधियाँ प्रदान करता है:
|
||||
|
||||
```python
|
||||
# Flow-scoped query (preferred)
|
||||
api = Api(url)
|
||||
flow = api.flow().id("default")
|
||||
|
||||
# Query with text (SDK computes embeddings)
|
||||
matches = flow.row_embeddings_query(
|
||||
text="Chestnut Street",
|
||||
collection="my_collection",
|
||||
schema_name="addresses",
|
||||
index_name="street_name", # Optional filter
|
||||
limit=10
|
||||
)
|
||||
|
||||
# Query with pre-computed vectors
|
||||
matches = flow.row_embeddings_query(
|
||||
vectors=[[0.1, 0.2, ...]],
|
||||
collection="my_collection",
|
||||
schema_name="addresses"
|
||||
)
|
||||
|
||||
# Each match contains:
|
||||
for match in matches:
|
||||
print(match.index_name) # e.g., "street_name"
|
||||
print(match.index_value) # e.g., ["CHESTNUT ST"]
|
||||
print(match.text) # e.g., "CHESTNUT ST"
|
||||
print(match.score) # e.g., 0.95
|
||||
```
|
||||
|
||||
#### कमांड लाइन यूटिलिटी
|
||||
|
||||
कमांड: `tg-invoke-row-embeddings`
|
||||
|
||||
```bash
|
||||
# Query by text (computes embedding automatically)
|
||||
tg-invoke-row-embeddings \
|
||||
--text "Chestnut Street" \
|
||||
--collection my_collection \
|
||||
--schema addresses \
|
||||
--index street_name \
|
||||
--limit 10
|
||||
|
||||
# Query by vector file
|
||||
tg-invoke-row-embeddings \
|
||||
--vectors vectors.json \
|
||||
--collection my_collection \
|
||||
--schema addresses
|
||||
|
||||
# Output formats
|
||||
tg-invoke-row-embeddings --text "..." --format json
|
||||
tg-invoke-row-embeddings --text "..." --format table
|
||||
```
|
||||
|
||||
#### विशिष्ट उपयोग पैटर्न
|
||||
|
||||
पंक्ति एम्बेडिंग क्वेरी का उपयोग आमतौर पर एक अस्पष्ट-से-सटीक लुकअप प्रवाह के हिस्से के रूप में किया जाता है:
|
||||
|
||||
```python
|
||||
# Step 1: Fuzzy search via embeddings
|
||||
matches = flow.row_embeddings_query(
|
||||
text="chestnut street",
|
||||
collection="geo",
|
||||
schema_name="streets"
|
||||
)
|
||||
|
||||
# Step 2: Exact lookup via GraphQL for full row data
|
||||
for match in matches:
|
||||
query = f'''
|
||||
query {{
|
||||
streets(where: {{ {match.index_name}: {{ eq: "{match.index_value[0]}" }} }}) {{
|
||||
street_name
|
||||
city
|
||||
zip_code
|
||||
}}
|
||||
}}
|
||||
'''
|
||||
rows = flow.rows_query(query, collection="geo")
|
||||
```
|
||||
|
||||
यह दो-चरणीय पैटर्न निम्नलिखित को सक्षम करता है:
|
||||
जब उपयोगकर्ता "Chestnut Street" खोजता है तो "CHESTNUT ST" खोजना।
|
||||
सभी फ़ील्ड के साथ पूरी पंक्ति डेटा प्राप्त करना।
|
||||
संरचित डेटा एक्सेस के साथ सिमेंटिक समानता को जोड़ना।
|
||||
|
||||
### पंक्ति डेटा का अंतर्ग्रहण
|
||||
|
||||
बाद के चरण में स्थगित। अन्य अंतर्ग्रहण परिवर्तनों के साथ मिलकर डिज़ाइन किया जाएगा।
|
||||
|
||||
## कार्यान्वयन प्रभाव
|
||||
|
||||
### वर्तमान स्थिति विश्लेषण
|
||||
|
||||
मौजूदा कार्यान्वयन में दो मुख्य घटक हैं:
|
||||
|
||||
| घटक | स्थान | लाइनें | विवरण |
|
||||
|-----------|----------|-------|-------------|
|
||||
| क्वेरी सेवा | `trustgraph-flow/trustgraph/query/objects/cassandra/service.py` | ~740 | एकरूप: GraphQL स्कीमा पीढ़ी, फ़िल्टर पार्सिंग, कैसेंड्रा क्वेरी, अनुरोध हैंडलिंग |
|
||||
| लेखक | `trustgraph-flow/trustgraph/storage/objects/cassandra/write.py` | ~540 | प्रति-स्कीमा तालिका निर्माण, द्वितीयक अनुक्रमणिका, सम्मिलित/हटाना |
|
||||
|
||||
**वर्तमान क्वेरी पैटर्न:**
|
||||
```sql
|
||||
SELECT * FROM {keyspace}.o_{schema_name}
|
||||
WHERE collection = 'X' AND email = 'foo@bar.com'
|
||||
ALLOW FILTERING
|
||||
```
|
||||
|
||||
**नई क्वेरी पैटर्न:**
|
||||
```sql
|
||||
SELECT * FROM {keyspace}.rows
|
||||
WHERE collection = 'X' AND schema_name = 'customers'
|
||||
AND index_name = 'email' AND index_value = ['foo@bar.com']
|
||||
```
|
||||
|
||||
### मुख्य परिवर्तन
|
||||
|
||||
1. **क्वेरी सिमेंटिक्स को सरल बनाया गया**: नया स्कीमा केवल `index_value` पर सटीक मिलान का समर्थन करता है। वर्तमान GraphQL फ़िल्टर (`gt`, `lt`, `contains`, आदि) या तो:
|
||||
लौटाए गए डेटा पर पोस्ट-फ़िल्टरिंग बन जाते हैं (यदि अभी भी आवश्यक हैं)
|
||||
अस्पष्ट मिलान के लिए एम्बेडिंग एपीआई का उपयोग करने के पक्ष में हटा दिए जाते हैं
|
||||
|
||||
2. **GraphQL कोड दृढ़ता से युग्मित है**: वर्तमान `service.py` स्ट्रॉबेरी टाइप जनरेशन, फ़िल्टर पार्सिंग और कैसेंड्रा-विशिष्ट प्रश्नों को बंडल करता है। एक और रो स्टोर बैकएंड जोड़ने से ~400 लाइनों का GraphQL कोड दोहराया जाएगा।
|
||||
|
||||
### प्रस्तावित रिफैक्टर
|
||||
|
||||
रिफैक्टर में दो भाग हैं:
|
||||
|
||||
#### 1. GraphQL कोड को अलग करें
|
||||
|
||||
पुन: प्रयोज्य GraphQL घटकों को एक साझा मॉड्यूल में निकालें:
|
||||
|
||||
```
|
||||
trustgraph-flow/trustgraph/query/graphql/
|
||||
├── __init__.py
|
||||
├── types.py # Filter types (IntFilter, StringFilter, FloatFilter)
|
||||
├── schema.py # Dynamic schema generation from RowSchema
|
||||
└── filters.py # Filter parsing utilities
|
||||
```
|
||||
|
||||
यह निम्नलिखित कार्य करता है:
|
||||
विभिन्न रो स्टोर बैकएंड में पुन: उपयोग
|
||||
चिंताओं का स्पष्ट अलगाव
|
||||
GraphQL लॉजिक का स्वतंत्र रूप से परीक्षण करना आसान
|
||||
|
||||
#### 2. नई टेबल स्कीमा को लागू करें
|
||||
|
||||
कैसेंड्रा-विशिष्ट कोड को एकीकृत टेबल का उपयोग करने के लिए रिफैक्टर करें:
|
||||
|
||||
**राइटर** (`trustgraph-flow/trustgraph/storage/rows/cassandra/`):
|
||||
प्रति-स्कीमा टेबल के बजाय एक एकल `rows` टेबल
|
||||
प्रति पंक्ति N प्रतियां लिखें (प्रत्येक इंडेक्स के लिए एक)
|
||||
`row_partitions` टेबल में पंजीकरण करें
|
||||
सरल टेबल निर्माण (एक बार सेटअप)
|
||||
|
||||
**क्वेरी सर्विस** (`trustgraph-flow/trustgraph/query/rows/cassandra/`):
|
||||
एकीकृत `rows` टेबल को क्वेरी करें
|
||||
स्कीमा पीढ़ी के लिए निकाले गए GraphQL मॉड्यूल का उपयोग करें
|
||||
सरलीकृत फ़िल्टर हैंडलिंग (केवल DB स्तर पर सटीक मिलान)
|
||||
|
||||
### मॉड्यूल का नाम बदलना
|
||||
|
||||
"ऑब्जेक्ट" से "रो" नामकरण को साफ करने के हिस्से के रूप में:
|
||||
|
||||
| वर्तमान | नया |
|
||||
|---------|-----|
|
||||
| `storage/objects/cassandra/` | `storage/rows/cassandra/` |
|
||||
| `query/objects/cassandra/` | `query/rows/cassandra/` |
|
||||
| `embeddings/object_embeddings/` | `embeddings/row_embeddings/` |
|
||||
|
||||
### नए मॉड्यूल
|
||||
|
||||
| मॉड्यूल | उद्देश्य |
|
||||
|--------|---------|
|
||||
| `trustgraph-flow/trustgraph/query/graphql/` | साझा GraphQL उपयोगिताएँ |
|
||||
| `trustgraph-flow/trustgraph/query/row_embeddings/qdrant/` | रो एम्बेडिंग क्वेरी एपीआई |
|
||||
| `trustgraph-flow/trustgraph/embeddings/row_embeddings/` | रो एम्बेडिंग गणना (स्टेज 1) |
|
||||
| `trustgraph-flow/trustgraph/storage/row_embeddings/qdrant/` | रो एम्बेडिंग भंडारण (स्टेज 2) |
|
||||
|
||||
## संदर्भ
|
||||
|
||||
[स्ट्रक्चर्ड डेटा तकनीकी विनिर्देश](structured-data.md)
|
||||
567
docs/tech-specs/hi/structured-data-descriptor.hi.md
Normal file
567
docs/tech-specs/hi/structured-data-descriptor.hi.md
Normal file
|
|
@ -0,0 +1,567 @@
|
|||
---
|
||||
layout: default
|
||||
title: "संरचित डेटा विवरण विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# संरचित डेटा विवरण विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
संरचित डेटा विवरण एक JSON-आधारित कॉन्फ़िगरेशन भाषा है जो यह बताती है कि संरचित डेटा को कैसे पार्स, रूपांतरित और ट्रस्टग्राफ में आयात किया जाए। यह डेटा इनग्रेसन के लिए एक घोषणात्मक दृष्टिकोण प्रदान करता है, जो कई इनपुट प्रारूपों और जटिल परिवर्तन पाइपलाइनों का समर्थन करता है, बिना कस्टम कोड की आवश्यकता के।
|
||||
|
||||
## मुख्य अवधारणाएँ
|
||||
|
||||
### 1. प्रारूप परिभाषा
|
||||
इनपुट फ़ाइल प्रकार और पार्सिंग विकल्पों का वर्णन करता है। यह निर्धारित करता है कि किस पार्सर का उपयोग करना है और स्रोत डेटा की व्याख्या कैसे करनी है।
|
||||
|
||||
### 2. फ़ील्ड मैपिंग
|
||||
स्रोत पथों को लक्ष्य फ़ील्ड में रूपांतरणों के साथ मैप करता है। यह परिभाषित करता है कि डेटा इनपुट स्रोतों से आउटपुट स्कीमा फ़ील्ड में कैसे प्रवाहित होता है।
|
||||
|
||||
### 3. परिवर्तन पाइपलाइन
|
||||
डेटा रूपांतरणों की श्रृंखला जो फ़ील्ड मानों पर लागू की जा सकती है, जिसमें शामिल हैं:
|
||||
डेटा सफाई (ट्रिम, सामान्यीकरण)
|
||||
प्रारूप रूपांतरण (तारीख पार्सिंग, प्रकार कास्टिंग)
|
||||
गणनाएँ (अंकगणित, स्ट्रिंग हेरफेर)
|
||||
लुकअप (संदर्भ तालिकाएँ, प्रतिस्थापन)
|
||||
|
||||
### 4. सत्यापन नियम
|
||||
डेटा गुणवत्ता जांच जो डेटा अखंडता सुनिश्चित करने के लिए लागू की जाती हैं:
|
||||
प्रकार सत्यापन
|
||||
सीमा जांच
|
||||
पैटर्न मिलान (रेगेक्स)
|
||||
आवश्यक फ़ील्ड सत्यापन
|
||||
कस्टम सत्यापन तर्क
|
||||
|
||||
### 5. वैश्विक सेटिंग्स
|
||||
कॉन्फ़िगरेशन जो संपूर्ण आयात प्रक्रिया पर लागू होता है:
|
||||
डेटा संवर्धन के लिए लुकअप तालिकाएँ
|
||||
वैश्विक चर और स्थिरांक
|
||||
आउटपुट प्रारूप विनिर्देश
|
||||
त्रुटि हैंडलिंग नीतियां
|
||||
|
||||
## कार्यान्वयन रणनीति
|
||||
|
||||
इम्पोर्टर कार्यान्वयन निम्नलिखित पाइपलाइन का पालन करता है:
|
||||
|
||||
1. **कॉन्फ़िगरेशन पार्स करें** - JSON विवरण लोड करें और मान्य करें
|
||||
2. **पार्सर आरंभ करें** - उपयुक्त पार्सर लोड करें (CSV, XML, JSON, आदि) `format.type` के आधार पर
|
||||
3. **पूर्व-प्रसंस्करण लागू करें** - वैश्विक फ़िल्टर और रूपांतरण निष्पादित करें
|
||||
4. **रिकॉर्ड संसाधित करें** - प्रत्येक इनपुट रिकॉर्ड के लिए:
|
||||
स्रोत पथों (JSONPath, XPath, कॉलम नाम) का उपयोग करके डेटा निकालें
|
||||
अनुक्रम में फ़ील्ड-स्तरीय रूपांतरण लागू करें
|
||||
परिभाषित नियमों के विरुद्ध परिणामों को मान्य करें
|
||||
लापता डेटा के लिए डिफ़ॉल्ट मान लागू करें
|
||||
5. **पोस्ट-प्रोसेसिंग लागू करें** - डुप्लिकेट हटाना, एकत्रीकरण, आदि निष्पादित करें।
|
||||
6. **आउटपुट उत्पन्न करें** - निर्दिष्ट लक्ष्य प्रारूप में डेटा उत्पन्न करें
|
||||
|
||||
## पथ अभिव्यक्ति समर्थन
|
||||
|
||||
विभिन्न इनपुट प्रारूप उपयुक्त पथ अभिव्यक्ति भाषाओं का उपयोग करते हैं:
|
||||
|
||||
**CSV**: कॉलम नाम या इंडेक्स (`"column_name"` या `"[2]"`)
|
||||
**JSON**: JSONPath सिंटैक्स (`"$.user.profile.email"`)
|
||||
**XML**: XPath एक्सप्रेशन (`"//product[@id='123']/price"`)
|
||||
**फिक्स्ड-विड्थ**: फ़ील्ड परिभाषाओं से फ़ील्ड नाम
|
||||
|
||||
## लाभ
|
||||
|
||||
**सिंगल कोडबेस** - एक इम्पोर्टर कई इनपुट प्रारूपों को संभालता है
|
||||
**उपयोगकर्ता के अनुकूल** - गैर-तकनीकी उपयोगकर्ता कॉन्फ़िगरेशन बना सकते हैं
|
||||
**पुन: प्रयोज्य** - कॉन्फ़िगरेशन साझा और संस्करणित किए जा सकते हैं
|
||||
**लचीला** - कस्टम कोडिंग के बिना जटिल रूपांतरण
|
||||
**मजबूत** - अंतर्निहित सत्यापन और व्यापक त्रुटि हैंडलिंग
|
||||
**रखरखाव योग्य** - घोषणात्मक दृष्टिकोण कार्यान्वयन जटिलता को कम करता है
|
||||
|
||||
## भाषा विनिर्देश
|
||||
|
||||
संरचित डेटा विवरण एक JSON कॉन्फ़िगरेशन प्रारूप का उपयोग करता है जिसमें निम्नलिखित शीर्ष-स्तरीय संरचना है:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"metadata": {
|
||||
"name": "Configuration Name",
|
||||
"description": "Description of what this config does",
|
||||
"author": "Author Name",
|
||||
"created": "2024-01-01T00:00:00Z"
|
||||
},
|
||||
"format": { ... },
|
||||
"globals": { ... },
|
||||
"preprocessing": [ ... ],
|
||||
"mappings": [ ... ],
|
||||
"postprocessing": [ ... ],
|
||||
"output": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
### प्रारूप परिभाषा
|
||||
|
||||
इनपुट डेटा प्रारूप और पार्सिंग विकल्पों का वर्णन करता है:
|
||||
|
||||
```json
|
||||
{
|
||||
"format": {
|
||||
"type": "csv|json|xml|fixed-width|excel|parquet",
|
||||
"encoding": "utf-8",
|
||||
"options": {
|
||||
// Format-specific options
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### सीएसवी प्रारूप विकल्प
|
||||
```json
|
||||
{
|
||||
"format": {
|
||||
"type": "csv",
|
||||
"options": {
|
||||
"delimiter": ",",
|
||||
"quote_char": "\"",
|
||||
"escape_char": "\\",
|
||||
"skip_rows": 1,
|
||||
"has_header": true,
|
||||
"null_values": ["", "NULL", "null", "N/A"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### जेएसओएन प्रारूप विकल्प
|
||||
```json
|
||||
{
|
||||
"format": {
|
||||
"type": "json",
|
||||
"options": {
|
||||
"root_path": "$.data",
|
||||
"array_mode": "records|single",
|
||||
"flatten": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### XML प्रारूप विकल्प
|
||||
```json
|
||||
{
|
||||
"format": {
|
||||
"type": "xml",
|
||||
"options": {
|
||||
"root_element": "//records/record",
|
||||
"namespaces": {
|
||||
"ns": "http://example.com/namespace"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### वैश्विक सेटिंग्स
|
||||
|
||||
लुकअप टेबल, वेरिएबल और वैश्विक कॉन्फ़िगरेशन को परिभाषित करें:
|
||||
|
||||
```json
|
||||
{
|
||||
"globals": {
|
||||
"variables": {
|
||||
"current_date": "2024-01-01",
|
||||
"batch_id": "BATCH_001",
|
||||
"default_confidence": 0.8
|
||||
},
|
||||
"lookup_tables": {
|
||||
"country_codes": {
|
||||
"US": "United States",
|
||||
"UK": "United Kingdom",
|
||||
"CA": "Canada"
|
||||
},
|
||||
"status_mapping": {
|
||||
"1": "active",
|
||||
"0": "inactive"
|
||||
}
|
||||
},
|
||||
"constants": {
|
||||
"source_system": "legacy_crm",
|
||||
"import_type": "full"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### फ़ील्ड मैपिंग
|
||||
|
||||
परिभाषित करें कि स्रोत डेटा लक्ष्य फ़ील्ड में कैसे मैप होता है, जिसमें रूपांतरण शामिल हैं:
|
||||
|
||||
```json
|
||||
{
|
||||
"mappings": [
|
||||
{
|
||||
"target_field": "person_name",
|
||||
"source": "$.name",
|
||||
"transforms": [
|
||||
{"type": "trim"},
|
||||
{"type": "title_case"},
|
||||
{"type": "required"}
|
||||
],
|
||||
"validation": [
|
||||
{"type": "min_length", "value": 2},
|
||||
{"type": "max_length", "value": 100},
|
||||
{"type": "pattern", "value": "^[A-Za-z\\s]+$"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"target_field": "age",
|
||||
"source": "$.age",
|
||||
"transforms": [
|
||||
{"type": "to_int"},
|
||||
{"type": "default", "value": 0}
|
||||
],
|
||||
"validation": [
|
||||
{"type": "range", "min": 0, "max": 150}
|
||||
]
|
||||
},
|
||||
{
|
||||
"target_field": "country",
|
||||
"source": "$.country_code",
|
||||
"transforms": [
|
||||
{"type": "lookup", "table": "country_codes"},
|
||||
{"type": "default", "value": "Unknown"}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### रूपांतरण प्रकार
|
||||
|
||||
उपलब्ध रूपांतरण फ़ंक्शन:
|
||||
|
||||
#### स्ट्रिंग रूपांतरण
|
||||
```json
|
||||
{"type": "trim"},
|
||||
{"type": "upper"},
|
||||
{"type": "lower"},
|
||||
{"type": "title_case"},
|
||||
{"type": "replace", "pattern": "old", "replacement": "new"},
|
||||
{"type": "regex_replace", "pattern": "\\d+", "replacement": "XXX"},
|
||||
{"type": "substring", "start": 0, "end": 10},
|
||||
{"type": "pad_left", "length": 10, "char": "0"}
|
||||
```
|
||||
|
||||
#### प्रकार रूपांतरण
|
||||
```json
|
||||
{"type": "to_string"},
|
||||
{"type": "to_int"},
|
||||
{"type": "to_float"},
|
||||
{"type": "to_bool"},
|
||||
{"type": "to_date", "format": "YYYY-MM-DD"},
|
||||
{"type": "parse_json"}
|
||||
```
|
||||
|
||||
#### डेटा संचालन
|
||||
```json
|
||||
{"type": "default", "value": "default_value"},
|
||||
{"type": "lookup", "table": "table_name"},
|
||||
{"type": "concat", "values": ["field1", " - ", "field2"]},
|
||||
{"type": "calculate", "expression": "${field1} + ${field2}"},
|
||||
{"type": "conditional", "condition": "${age} > 18", "true_value": "adult", "false_value": "minor"}
|
||||
```
|
||||
|
||||
### सत्यापन नियम
|
||||
|
||||
कॉन्फ़िगर करने योग्य त्रुटि प्रबंधन के साथ डेटा गुणवत्ता जांच:
|
||||
|
||||
#### बुनियादी सत्यापन
|
||||
```json
|
||||
{"type": "required"},
|
||||
{"type": "not_null"},
|
||||
{"type": "min_length", "value": 5},
|
||||
{"type": "max_length", "value": 100},
|
||||
{"type": "range", "min": 0, "max": 1000},
|
||||
{"type": "pattern", "value": "^[A-Z]{2,3}$"},
|
||||
{"type": "in_list", "values": ["active", "inactive", "pending"]}
|
||||
```
|
||||
|
||||
#### कस्टम सत्यापन
|
||||
```json
|
||||
{
|
||||
"type": "custom",
|
||||
"expression": "${age} >= 18 && ${country} == 'US'",
|
||||
"message": "Must be 18+ and in US"
|
||||
},
|
||||
{
|
||||
"type": "cross_field",
|
||||
"fields": ["start_date", "end_date"],
|
||||
"expression": "${start_date} < ${end_date}",
|
||||
"message": "Start date must be before end date"
|
||||
}
|
||||
```
|
||||
|
||||
### पूर्व-प्रसंस्करण और उत्तर-प्रसंस्करण
|
||||
|
||||
फ़ील्ड मैपिंग से पहले/बाद लागू किए गए वैश्विक ऑपरेशन:
|
||||
|
||||
```json
|
||||
{
|
||||
"preprocessing": [
|
||||
{
|
||||
"type": "filter",
|
||||
"condition": "${status} != 'deleted'"
|
||||
},
|
||||
{
|
||||
"type": "sort",
|
||||
"field": "created_date",
|
||||
"order": "asc"
|
||||
}
|
||||
],
|
||||
"postprocessing": [
|
||||
{
|
||||
"type": "deduplicate",
|
||||
"key_fields": ["email", "phone"]
|
||||
},
|
||||
{
|
||||
"type": "aggregate",
|
||||
"group_by": ["country"],
|
||||
"functions": {
|
||||
"total_count": {"type": "count"},
|
||||
"avg_age": {"type": "avg", "field": "age"}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### आउटपुट कॉन्फ़िगरेशन
|
||||
|
||||
परिभाषित करें कि संसाधित डेटा को कैसे आउटपुट किया जाना चाहिए:
|
||||
|
||||
```json
|
||||
{
|
||||
"output": {
|
||||
"format": "trustgraph-objects",
|
||||
"schema_name": "person",
|
||||
"options": {
|
||||
"batch_size": 1000,
|
||||
"confidence": 0.9,
|
||||
"source_span_field": "raw_text",
|
||||
"metadata": {
|
||||
"source": "crm_import",
|
||||
"version": "1.0"
|
||||
}
|
||||
},
|
||||
"error_handling": {
|
||||
"on_validation_error": "skip|fail|log",
|
||||
"on_transform_error": "skip|fail|default",
|
||||
"max_errors": 100,
|
||||
"error_output": "errors.json"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## पूर्ण उदाहरण
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"metadata": {
|
||||
"name": "Customer Import from CRM CSV",
|
||||
"description": "Imports customer data from legacy CRM system",
|
||||
"author": "Data Team",
|
||||
"created": "2024-01-01T00:00:00Z"
|
||||
},
|
||||
"format": {
|
||||
"type": "csv",
|
||||
"encoding": "utf-8",
|
||||
"options": {
|
||||
"delimiter": ",",
|
||||
"has_header": true,
|
||||
"skip_rows": 1
|
||||
}
|
||||
},
|
||||
"globals": {
|
||||
"variables": {
|
||||
"import_date": "2024-01-01",
|
||||
"default_confidence": 0.85
|
||||
},
|
||||
"lookup_tables": {
|
||||
"country_codes": {
|
||||
"US": "United States",
|
||||
"CA": "Canada",
|
||||
"UK": "United Kingdom"
|
||||
}
|
||||
}
|
||||
},
|
||||
"preprocessing": [
|
||||
{
|
||||
"type": "filter",
|
||||
"condition": "${status} == 'active'"
|
||||
}
|
||||
],
|
||||
"mappings": [
|
||||
{
|
||||
"target_field": "full_name",
|
||||
"source": "customer_name",
|
||||
"transforms": [
|
||||
{"type": "trim"},
|
||||
{"type": "title_case"}
|
||||
],
|
||||
"validation": [
|
||||
{"type": "required"},
|
||||
{"type": "min_length", "value": 2}
|
||||
]
|
||||
},
|
||||
{
|
||||
"target_field": "email",
|
||||
"source": "email_address",
|
||||
"transforms": [
|
||||
{"type": "trim"},
|
||||
{"type": "lower"}
|
||||
],
|
||||
"validation": [
|
||||
{"type": "pattern", "value": "^[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,}$"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"target_field": "age",
|
||||
"source": "age",
|
||||
"transforms": [
|
||||
{"type": "to_int"},
|
||||
{"type": "default", "value": 0}
|
||||
],
|
||||
"validation": [
|
||||
{"type": "range", "min": 0, "max": 120}
|
||||
]
|
||||
},
|
||||
{
|
||||
"target_field": "country",
|
||||
"source": "country_code",
|
||||
"transforms": [
|
||||
{"type": "lookup", "table": "country_codes"},
|
||||
{"type": "default", "value": "Unknown"}
|
||||
]
|
||||
}
|
||||
],
|
||||
"output": {
|
||||
"format": "trustgraph-objects",
|
||||
"schema_name": "customer",
|
||||
"options": {
|
||||
"confidence": "${default_confidence}",
|
||||
"batch_size": 500
|
||||
},
|
||||
"error_handling": {
|
||||
"on_validation_error": "log",
|
||||
"max_errors": 50
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## एलएलएम प्रॉम्प्ट (LLM Prompt) का उपयोग करके विवरण (डेस्क्रिप्टर) निर्माण
|
||||
|
||||
निम्नलिखित प्रॉम्प्ट का उपयोग करके, एक एलएलएम (LLM) नमूना डेटा का विश्लेषण कर सकता है और एक विवरण कॉन्फ़िगरेशन उत्पन्न कर सकता है:
|
||||
|
||||
```
|
||||
I need you to analyze the provided data sample and create a Structured Data Descriptor configuration in JSON format.
|
||||
|
||||
The descriptor should follow this specification:
|
||||
- version: "1.0"
|
||||
- metadata: Configuration name, description, author, and creation date
|
||||
- format: Input format type and parsing options
|
||||
- globals: Variables, lookup tables, and constants
|
||||
- preprocessing: Filters and transformations applied before mapping
|
||||
- mappings: Field-by-field mapping from source to target with transformations and validations
|
||||
- postprocessing: Operations like deduplication or aggregation
|
||||
- output: Target format and error handling configuration
|
||||
|
||||
ANALYZE THE DATA:
|
||||
1. Identify the format (CSV, JSON, XML, etc.)
|
||||
2. Detect delimiters, encodings, and structure
|
||||
3. Find data types for each field
|
||||
4. Identify patterns and constraints
|
||||
5. Look for fields that need cleaning or transformation
|
||||
6. Find relationships between fields
|
||||
7. Identify lookup opportunities (codes that map to values)
|
||||
8. Detect required vs optional fields
|
||||
|
||||
CREATE THE DESCRIPTOR:
|
||||
For each field in the sample data:
|
||||
- Map it to an appropriate target field name
|
||||
- Add necessary transformations (trim, case conversion, type casting)
|
||||
- Include appropriate validations (required, patterns, ranges)
|
||||
- Set defaults for missing values
|
||||
|
||||
Include preprocessing if needed:
|
||||
- Filters to exclude invalid records
|
||||
- Sorting requirements
|
||||
|
||||
Include postprocessing if beneficial:
|
||||
- Deduplication on key fields
|
||||
- Aggregation for summary data
|
||||
|
||||
Configure output for TrustGraph:
|
||||
- format: "trustgraph-objects"
|
||||
- schema_name: Based on the data entity type
|
||||
- Appropriate error handling
|
||||
|
||||
DATA SAMPLE:
|
||||
[Insert data sample here]
|
||||
|
||||
ADDITIONAL CONTEXT (optional):
|
||||
- Target schema name: [if known]
|
||||
- Business rules: [any specific requirements]
|
||||
- Data quality issues to address: [known problems]
|
||||
|
||||
Generate a complete, valid Structured Data Descriptor configuration that will properly import this data into TrustGraph. Include comments explaining key decisions.
|
||||
```
|
||||
|
||||
### उदाहरण उपयोग संकेत
|
||||
|
||||
```
|
||||
I need you to analyze the provided data sample and create a Structured Data Descriptor configuration in JSON format.
|
||||
|
||||
[Standard instructions from above...]
|
||||
|
||||
DATA SAMPLE:
|
||||
```csv
|
||||
ग्राहक आईडी, नाम, ईमेल, आयु, देश, स्थिति, शामिल होने की तिथि, कुल खरीदारी
|
||||
1001, "स्मिथ, जॉन", john.smith@email.com, 35, यूएस, 1, 2023-01-15, 5420.50
|
||||
1002, "डो, जेन", JANE.DOE@GMAIL.COM, 28, कनाडा, 1, 2023-03-22, 3200.00
|
||||
1003, "बॉब जॉनसन", bob@, 62, यूके, 0, 2022-11-01, 0
|
||||
1004, "एलिस चेन", "alice.chen@company.org", 41, यूएस, 1, 2023-06-10, 8900.25
|
||||
1005, , invalid-email, 25, XX, 1, 2024-01-01, 100
|
||||
```
|
||||
|
||||
ADDITIONAL CONTEXT:
|
||||
- Target schema name: customer
|
||||
- Business rules: Email should be valid and lowercase, names should be title case
|
||||
- Data quality issues: Some emails are invalid, some names are missing, country codes need mapping
|
||||
```
|
||||
|
||||
### मौजूदा डेटा का विश्लेषण करने के लिए संकेत (प्रॉम्प्ट) बिना नमूने के
|
||||
|
||||
```
|
||||
I need you to help me create a Structured Data Descriptor configuration for importing [data type] data.
|
||||
|
||||
The source data has these characteristics:
|
||||
- Format: [CSV/JSON/XML/etc]
|
||||
- Fields: [list the fields]
|
||||
- Data quality issues: [describe any known issues]
|
||||
- Volume: [approximate number of records]
|
||||
|
||||
Requirements:
|
||||
- [List any specific transformation needs]
|
||||
- [List any validation requirements]
|
||||
- [List any business rules]
|
||||
|
||||
Please generate a Structured Data Descriptor configuration that will:
|
||||
1. Parse the input format correctly
|
||||
2. Clean and standardize the data
|
||||
3. Validate according to the requirements
|
||||
4. Handle errors gracefully
|
||||
5. Output in TrustGraph ExtractedObject format
|
||||
|
||||
Focus on making the configuration robust and reusable.
|
||||
```
|
||||
147
docs/tech-specs/hi/structured-data-schemas.hi.md
Normal file
147
docs/tech-specs/hi/structured-data-schemas.hi.md
Normal file
|
|
@ -0,0 +1,147 @@
|
|||
---
|
||||
layout: default
|
||||
title: "संरचित डेटा पल्सर स्कीमा परिवर्तन"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# संरचित डेटा पल्सर स्कीमा परिवर्तन
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
`STRUCTURED_DATA.md` विनिर्देश के आधार पर, यह दस्तावेज़ आवश्यक पल्सर स्कीमा परिवर्धन और संशोधन प्रस्तावित करता है ताकि ट्रस्टग्राफ में संरचित डेटा क्षमताओं का समर्थन किया जा सके।
|
||||
|
||||
## आवश्यक स्कीमा परिवर्तन
|
||||
|
||||
### 1. कोर स्कीमा संवर्द्धन
|
||||
|
||||
#### उन्नत फ़ील्ड परिभाषा
|
||||
`core/primitives.py` में मौजूदा `Field` वर्ग में अतिरिक्त गुण होने चाहिए:
|
||||
|
||||
```python
|
||||
class Field(Record):
|
||||
name = String()
|
||||
type = String() # int, string, long, bool, float, double, timestamp
|
||||
size = Integer()
|
||||
primary = Boolean()
|
||||
description = String()
|
||||
# नए फ़ील्ड:
|
||||
required = Boolean() # क्या फ़ील्ड अनिवार्य है
|
||||
enum_values = Array(String()) # एनम प्रकार के फ़ील्ड के लिए
|
||||
indexed = Boolean() # क्या फ़ील्ड को अनुक्रमित किया जाना चाहिए
|
||||
```
|
||||
|
||||
### 2. नई ज्ञान स्कीमा
|
||||
|
||||
#### 2.1 संरचित डेटा सबमिशन
|
||||
नई फ़ाइल: `knowledge/structured.py`
|
||||
|
||||
```python
|
||||
from pulsar.schema import Record, String, Bytes, Map
|
||||
from ..core.metadata import Metadata
|
||||
|
||||
class StructuredDataSubmission(Record):
|
||||
metadata = Metadata()
|
||||
format = String() # "json", "csv", "xml"
|
||||
schema_name = String() # कॉन्फ़िगरेशन में स्कीमा का संदर्भ
|
||||
data = Bytes() # संसाधित करने के लिए कच्चा डेटा
|
||||
options = Map(String()) # प्रारूप-विशिष्ट विकल्प
|
||||
```
|
||||
|
||||
### 3. नई सेवा स्कीमा
|
||||
|
||||
#### 3.1 एनएलपी से संरचित क्वेरी सेवा
|
||||
नई फ़ाइल: `services/nlp_query.py`
|
||||
|
||||
```python
|
||||
from pulsar.schema import Record, String, Array, Map, Integer, Double
|
||||
from ..core.primitives import Error
|
||||
|
||||
class NLPToStructuredQueryRequest(Record):
|
||||
natural_language_query = String()
|
||||
max_results = Integer()
|
||||
context_hints = Map(String()) # क्वेरी पीढ़ी के लिए वैकल्पिक संदर्भ
|
||||
|
||||
class NLPToStructuredQueryResponse(Record):
|
||||
error = Error()
|
||||
graphql_query = String() # उत्पन्न ग्राफ़क्यूएल क्वेरी
|
||||
variables = Map(String()) # यदि कोई हो तो ग्राफ़क्यूएल चर
|
||||
detected_schemas = Array(String()) # कौन सी स्कीमा क्वेरी को लक्षित करती हैं
|
||||
confidence = Double()
|
||||
```
|
||||
|
||||
#### 3.2 संरचित क्वेरी सेवा
|
||||
नई फ़ाइल: `services/structured_query.py`
|
||||
|
||||
```python
|
||||
from pulsar.schema import Record, String, Map, Array
|
||||
from ..core.primitives import Error
|
||||
|
||||
class StructuredQueryRequest(Record):
|
||||
query = String() # ग्राफ़क्यूएल क्वेरी
|
||||
variables = Map(String()) # ग्राफ़क्यूएल चर
|
||||
operation_name = String() # मल्टी-ऑपरेशन दस्तावेजों के लिए वैकल्पिक ऑपरेशन नाम
|
||||
|
||||
class StructuredQueryResponse(Record):
|
||||
error = Error()
|
||||
data = String() # JSON-एन्कोडेड ग्राफ़क्यूएल प्रतिक्रिया डेटा
|
||||
errors = Array(String()) # यदि कोई हो तो ग्राफ़क्यूएल त्रुटियां
|
||||
```
|
||||
|
||||
#### 2.2 ऑब्जेक्ट निष्कर्षण आउटपुट
|
||||
नई फ़ाइल: `knowledge/object.py`
|
||||
|
||||
```python
|
||||
from pulsar.schema import Record, String, Map, Double
|
||||
from ..core.metadata import Metadata
|
||||
|
||||
class ExtractedObject(Record):
|
||||
metadata = Metadata()
|
||||
schema_name = String() # यह ऑब्जेक्ट किस स्कीमा से संबंधित है
|
||||
values = Map(String()) # फ़ील्ड नाम -> मान
|
||||
confidence = Double()
|
||||
source_span = String() # पाठ का वह भाग जहां ऑब्जेक्ट पाया गया था
|
||||
```
|
||||
|
||||
### 4. उन्नत ज्ञान स्कीमा
|
||||
|
||||
#### 4.1 ऑब्जेक्ट एम्बेडिंग संवर्द्धन
|
||||
संरचित ऑब्जेक्ट एम्बेडिंग को बेहतर ढंग से समर्थन करने के लिए `knowledge/embeddings.py` को अपडेट करें:
|
||||
|
||||
```python
|
||||
class StructuredObjectEmbedding(Record):
|
||||
metadata = Metadata()
|
||||
vectors = Array(Array(Double()))
|
||||
schema_name = String()
|
||||
object_id = String() # प्राथमिक कुंजी मान
|
||||
field_embeddings = Map(Array(Double())) # प्रति-फ़ील्ड एम्बेडिंग
|
||||
```
|
||||
|
||||
## एकीकरण बिंदु
|
||||
|
||||
### फ्लो एकीकरण
|
||||
|
||||
इन स्कीमा का उपयोग नए फ्लो मॉड्यूल द्वारा किया जाएगा:
|
||||
- `trustgraph-flow/trustgraph/decoding/structured` - `StructuredDataSubmission` का उपयोग करता है
|
||||
- `trustgraph-flow/trustgraph/query/nlp_query/cassandra` - एनएलपी क्वेरी स्कीमा का उपयोग करता है
|
||||
- `trustgraph-flow/trustgraph/query/objects/cassandra` - संरचित क्वेरी स्कीमा का उपयोग करता है
|
||||
- `trustgraph-flow/trustgraph/extract/object/row/` - `Chunk` का उपभोग करता है, `ExtractedObject` उत्पन्न करता है
|
||||
- `trustgraph-flow/trustgraph/storage/objects/cassandra` - `Rows` स्कीमा का उपयोग करता है
|
||||
- `trustgraph-flow/trustgraph/embeddings/object_embeddings/qdrant` - ऑब्जेक्ट एम्बेडिंग स्कीमा का उपयोग करता है
|
||||
|
||||
## कार्यान्वयन नोट्स
|
||||
|
||||
1. **स्कीमा संस्करण:** भविष्य के माइग्रेशन समर्थन के लिए `RowSchema` में एक `version` फ़ील्ड जोड़ने पर विचार करें।
|
||||
2. **प्रकार प्रणाली:** `Field.type` को सभी कैसेंड्रा मूल प्रकारों का समर्थन करना चाहिए।
|
||||
3. **बैच ऑपरेशन:** अधिकांश सेवाओं को एकल और बैच दोनों ऑपरेशन का समर्थन करना चाहिए।
|
||||
4. **त्रुटि प्रबंधन:** सभी नई सेवाओं में सुसंगत त्रुटि रिपोर्टिंग।
|
||||
5. **पिछड़ा संगतता:** मौजूदा स्कीमा अपरिवर्तित रहते हैं, केवल छोटे फ़ील्ड संवर्द्धन को छोड़कर।
|
||||
|
||||
## अगले कदम
|
||||
|
||||
1. नई संरचना में स्कीमा फ़ाइलें लागू करें।
|
||||
2. मौजूदा सेवाओं को नए स्कीमा प्रकारों को पहचानने के लिए अपडेट करें।
|
||||
3. इन स्कीमा का उपयोग करने वाले फ्लो मॉड्यूल लागू करें।
|
||||
4. नई सेवाओं के लिए गेटवे/रिवर्स-गेटवे एंडपॉइंट बनाएं।
|
||||
5. स्कीमा सत्यापन के लिए यूनिट परीक्षण बनाएं।
|
||||
258
docs/tech-specs/hi/structured-data.hi.md
Normal file
258
docs/tech-specs/hi/structured-data.hi.md
Normal file
|
|
@ -0,0 +1,258 @@
|
|||
---
|
||||
layout: default
|
||||
title: "संरचित डेटा तकनीकी विनिर्देश"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# संरचित डेटा तकनीकी विनिर्देश
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह विनिर्देश ट्रस्टग्राफ को संरचित डेटा प्रवाह के साथ एकीकृत करने का वर्णन करता है, जिससे सिस्टम डेटा के साथ काम कर सके जिसे तालिकाओं में पंक्तियों या ऑब्जेक्ट स्टोर में ऑब्जेक्ट के रूप में दर्शाया जा सकता है। यह एकीकरण चार प्राथमिक उपयोग मामलों का समर्थन करता है:
|
||||
|
||||
1. **असंरचित से संरचित निष्कर्षण**: असंरचित डेटा स्रोतों को पढ़ें, ऑब्जेक्ट संरचनाओं की पहचान करें और उन्हें निकालें, और उन्हें एक सारणीबद्ध प्रारूप में संग्रहीत करें।
|
||||
2. **संरचित डेटा का अंतर्ग्रहण**: डेटा को जो पहले से ही संरचित प्रारूपों में है, उसे सीधे संरचित स्टोर में निकाले गए डेटा के साथ लोड करें।
|
||||
3. **प्राकृतिक भाषा प्रश्न**: प्राकृतिक भाषा के प्रश्नों को संरचित प्रश्नों में परिवर्तित करें ताकि स्टोर से मिलान करने वाले डेटा को निकाला जा सके।
|
||||
4. **प्रत्यक्ष संरचित प्रश्न**: सटीक डेटा पुनर्प्राप्ति के लिए डेटा स्टोर के खिलाफ सीधे संरचित प्रश्नों को निष्पादित करें।
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
**एकीकृत डेटा एक्सेस**: ट्रस्टग्राफ के भीतर संरचित और असंरचित दोनों डेटा तक पहुंचने के लिए एक एकल इंटरफ़ेस प्रदान करें।
|
||||
**निर्बाध एकीकरण**: ट्रस्टग्राफ के ग्राफ-आधारित ज्ञान प्रतिनिधित्व और पारंपरिक संरचित डेटा प्रारूपों के बीच सुचारू अंतर-संचालन को सक्षम करें।
|
||||
**लचीला निष्कर्षण**: विभिन्न असंरचित स्रोतों (दस्तावेज़, पाठ, आदि) से संरचित डेटा के स्वचालित निष्कर्षण का समर्थन करें।
|
||||
**प्रश्न बहुमुखी प्रतिभा**: उपयोगकर्ताओं को प्राकृतिक भाषा और संरचित प्रश्न भाषाओं दोनों का उपयोग करके डेटा क्वेरी करने की अनुमति दें।
|
||||
**डेटा स्थिरता**: विभिन्न डेटा प्रतिनिधित्व में डेटा अखंडता और स्थिरता बनाए रखें।
|
||||
**प्रदर्शन अनुकूलन**: पैमाने पर संरचित डेटा के कुशल भंडारण और पुनर्प्राप्ति सुनिश्चित करें।
|
||||
**स्कीमा लचीलापन**: विभिन्न डेटा स्रोतों को समायोजित करने के लिए स्कीमा-ऑन-राइट और स्कीमा-ऑन-रीड दोनों दृष्टिकोणों का समर्थन करें।
|
||||
**पिछड़ा संगतता**: संरचित डेटा क्षमताओं को जोड़ते समय मौजूदा ट्रस्टग्राफ कार्यक्षमता को संरक्षित करें।
|
||||
|
||||
## पृष्ठभूमि
|
||||
|
||||
ट्रस्टग्राफ वर्तमान में असंरचित डेटा को संसाधित करने और विभिन्न स्रोतों से ज्ञान ग्राफ बनाने में उत्कृष्ट है। हालाँकि, कई उद्यम उपयोग मामलों में डेटा शामिल होता है जो स्वाभाविक रूप से संरचित होता है - ग्राहक रिकॉर्ड, लेनदेन लॉग, इन्वेंट्री डेटाबेस और अन्य सारणीबद्ध डेटासेट। इन संरचित डेटासेट का अक्सर व्यापक अंतर्दृष्टि प्रदान करने के लिए असंरचित सामग्री के साथ विश्लेषण करने की आवश्यकता होती है।
|
||||
|
||||
वर्तमान सीमाएँ शामिल हैं:
|
||||
पूर्व-संरचित डेटा प्रारूपों (CSV, JSON सरणियों, डेटाबेस निर्यात) को अंतर्ग्रहण करने के लिए कोई देशी समर्थन नहीं।
|
||||
दस्तावेज़ों से सारणीबद्ध डेटा निकालते समय अंतर्निहित संरचना को संरक्षित करने में असमर्थता।
|
||||
संरचित डेटा पैटर्न के लिए कुशल प्रश्न तंत्र की कमी।
|
||||
SQL-जैसे प्रश्नों और ट्रस्टग्राफ के ग्राफ प्रश्नों के बीच कोई पुल नहीं।
|
||||
|
||||
यह विनिर्देश इन कमियों को एक संरचित डेटा परत पेश करके संबोधित करता है जो ट्रस्टग्राफ की मौजूदा क्षमताओं को पूरक करता है। संरचित डेटा का मूल रूप से समर्थन करके, ट्रस्टग्राफ:
|
||||
संरचित और असंरचित दोनों डेटा विश्लेषण के लिए एक एकीकृत मंच के रूप में कार्य कर सकता है।
|
||||
ग्राफ संबंधों और सारणीबद्ध डेटा दोनों को कवर करने वाले हाइब्रिड प्रश्नों को सक्षम कर सकता है।
|
||||
संरचित डेटा के साथ काम करने के लिए अभ्यस्त उपयोगकर्ताओं के लिए परिचित इंटरफेस प्रदान कर सकता है।
|
||||
डेटा एकीकरण और व्यावसायिक बुद्धिमत्ता में नए उपयोग मामलों को अनलॉक कर सकता है।
|
||||
|
||||
## तकनीकी डिजाइन
|
||||
|
||||
### वास्तुकला
|
||||
|
||||
संरचित डेटा एकीकरण के लिए निम्नलिखित तकनीकी घटकों की आवश्यकता होती है:
|
||||
|
||||
1. **एनएलपी-टू-स्ट्रक्चर्ड-क्वेरी सेवा**
|
||||
प्राकृतिक भाषा के प्रश्नों को संरचित प्रश्नों में परिवर्तित करता है।
|
||||
कई प्रश्न भाषा लक्ष्यों का समर्थन करता है (प्रारंभ में SQL-जैसे सिंटैक्स)।
|
||||
मौजूदा ट्रस्टग्राफ एनएलपी क्षमताओं के साथ एकीकृत होता है।
|
||||
|
||||
मॉड्यूल: trustgraph-flow/trustgraph/query/nlp_query/cassandra
|
||||
|
||||
2. **कॉन्फ़िगरेशन स्कीमा समर्थन** ✅ **[पूर्ण]**
|
||||
संरचित डेटा स्कीमा को संग्रहीत करने के लिए विस्तारित कॉन्फ़िगरेशन सिस्टम।
|
||||
तालिका संरचनाओं, फ़ील्ड प्रकारों और संबंधों को परिभाषित करने का समर्थन।
|
||||
स्कीमा संस्करण और माइग्रेशन क्षमताएं।
|
||||
|
||||
3. **ऑब्जेक्ट निष्कर्षण मॉड्यूल** ✅ **[पूर्ण]**
|
||||
बेहतर ज्ञान निष्कर्षण प्रवाह एकीकरण।
|
||||
असंरचित स्रोतों से संरचित ऑब्जेक्ट की पहचान और निष्कर्षण।
|
||||
उत्पत्ति और आत्मविश्वास स्कोर बनाए रखता है।
|
||||
एक कॉन्फ़िग हैंडलर (उदाहरण: trustgraph-flow/trustgraph/prompt/template/service.py) को कॉन्फ़िग डेटा प्राप्त करने और स्कीमा जानकारी को डिकोड करने के लिए पंजीकृत करता है।
|
||||
ऑब्जेक्ट प्राप्त करता है और उन्हें पल्सर कतार पर डिलीवरी के लिए एक्सट्रैक्टेडऑब्जेक्ट ऑब्जेक्ट में डिकोड करता है।
|
||||
ध्यान दें: `trustgraph-flow/trustgraph/extract/object/row/` पर मौजूदा कोड है। यह एक पिछला प्रयास था और इसे वर्तमान एपीआई के अनुरूप नहीं होने के कारण प्रमुख रूप से फिर से तैयार करने की आवश्यकता होगी। यदि यह उपयोगी है तो इसका उपयोग करें, यदि नहीं तो इसे खरोंच से शुरू करें।
|
||||
एक कमांड-लाइन इंटरफ़ेस की आवश्यकता है: `kg-extract-objects`
|
||||
|
||||
मॉड्यूल: trustgraph-flow/trustgraph/extract/kg/objects/
|
||||
|
||||
4. **संरचित स्टोर लेखक मॉड्यूल** ✅ **[पूर्ण]**
|
||||
पल्सर कतारों से एक्सट्रैक्टेडऑब्जेक्ट प्रारूप में ऑब्जेक्ट प्राप्त करता है।
|
||||
Apache Cassandra को संरचित डेटा स्टोर के रूप में लक्षित करने वाला प्रारंभिक कार्यान्वयन।
|
||||
सामना किए गए स्कीमा के आधार पर गतिशील तालिका निर्माण को संभालता है।
|
||||
स्कीमा-से-कैसेंड्रा तालिका मैपिंग और डेटा परिवर्तन का प्रबंधन करता है।
|
||||
प्रदर्शन अनुकूलन के लिए बैच और स्ट्रीमिंग लेखन संचालन प्रदान करता है।
|
||||
कोई पल्सर आउटपुट नहीं - यह डेटा प्रवाह में एक टर्मिनल सेवा है।
|
||||
|
||||
**स्कीमा हैंडलिंग**:
|
||||
स्कीमा संदर्भों के लिए आने वाले एक्सट्रैक्टेडऑब्जेक्ट संदेशों की निगरानी करता है।
|
||||
पहली बार जब एक नया स्कीमा सामना किया जाता है, तो स्वचालित रूप से संबंधित कैसेंड्रा तालिका बनाता है।
|
||||
ज्ञात स्कीमा के एक कैश को बनाए रखता है ताकि अनावश्यक तालिका निर्माण प्रयासों से बचा जा सके।
|
||||
इस पर विचार करना चाहिए कि स्कीमा परिभाषाएँ सीधे प्राप्त की जानी चाहिए या एक्सट्रैक्टेडऑब्जेक्ट संदेशों में स्कीमा नामों पर भरोसा किया जाना चाहिए।
|
||||
|
||||
**कैसेंड्रा टेबल मैपिंग**:
|
||||
कीस्पेस का नाम एक्सट्रैक्टेडऑब्जेक्ट के मेटाडेटा से `user` फ़ील्ड से लिया गया है।
|
||||
टेबल का नाम एक्सट्रैक्टेडऑब्जेक्ट से `schema_name` फ़ील्ड से लिया गया है।
|
||||
मेटाडेटा से कलेक्शन को पार्टीशन कुंजी का हिस्सा बनाया जाता है ताकि:
|
||||
कैसेंड्रा नोड्स में डेटा का प्राकृतिक वितरण सुनिश्चित हो सके।
|
||||
एक विशिष्ट कलेक्शन के भीतर कुशल क्वेरीज़ संभव हों।
|
||||
विभिन्न डेटा आयात/स्रोत के बीच तार्किक अलगाव सुनिश्चित हो सके।
|
||||
प्राइमरी की संरचना: `PRIMARY KEY ((collection, <schema_primary_key_fields>), <clustering_keys>)`
|
||||
कलेक्शन हमेशा पार्टीशन कुंजी का पहला घटक होता है।
|
||||
स्कीमा-परिभाषित प्राइमरी की फ़ील्ड, समग्र पार्टीशन कुंजी का हिस्सा होते हैं।
|
||||
इसके लिए क्वेरीज़ में कलेक्शन को निर्दिष्ट करने की आवश्यकता होती है, जिससे प्रदर्शन पूर्वानुमेय रहता है।
|
||||
फ़ील्ड परिभाषाएँ कैसेंड्रा कॉलम में टाइप रूपांतरण के साथ मैप होती हैं:
|
||||
`string` → `text`
|
||||
`integer` → `int` या `bigint`, आकार के संकेत के आधार पर।
|
||||
`float` → `float` या `double`, परिशुद्धता की आवश्यकताओं के आधार पर।
|
||||
`boolean` → `boolean`
|
||||
`timestamp` → `timestamp`
|
||||
`enum` → `text`, एप्लिकेशन-स्तरीय सत्यापन के साथ।
|
||||
अनुक्रमित फ़ील्ड कैसेंड्रा सेकेंडरी इंडेक्स बनाते हैं (प्राइमरी कुंजी में पहले से मौजूद फ़ील्ड को छोड़कर)।
|
||||
आवश्यक फ़ील्ड एप्लिकेशन स्तर पर लागू किए जाते हैं (कैसेंड्रा NOT NULL का समर्थन नहीं करता है)।
|
||||
|
||||
**ऑब्जेक्ट स्टोरेज**:
|
||||
एक्सट्रैक्टेडऑब्जेक्ट.वैल्यूज़ मैप से मान निकाले जाते हैं।
|
||||
सम्मिलन से पहले टाइप रूपांतरण और सत्यापन किया जाता है।
|
||||
गुम वैकल्पिक फ़ील्ड को कुशलतापूर्वक संभाला जाता है।
|
||||
ऑब्जेक्ट की उत्पत्ति के बारे में मेटाडेटा बनाए रखा जाता है (स्रोत दस्तावेज़, आत्मविश्वास स्कोर)।
|
||||
संदेश पुनरावृत्ति परिदृश्यों को संभालने के लिए आइडेंपोटेंट राइट का समर्थन करता है।
|
||||
|
||||
**कार्यान्वयन नोट्स**:
|
||||
`trustgraph-flow/trustgraph/storage/objects/cassandra/` पर मौजूद मौजूदा कोड पुराना है और वर्तमान एपीआई के अनुरूप नहीं है।
|
||||
`trustgraph-flow/trustgraph/storage/triples/cassandra` को एक कार्यशील स्टोरेज प्रोसेसर के उदाहरण के रूप में संदर्भित किया जाना चाहिए।
|
||||
पुन: उपयोग करने योग्य घटकों के लिए मौजूदा कोड का मूल्यांकन किया जाना चाहिए, फिर रिफैक्टर या फिर से लिखने का निर्णय लिया जाना चाहिए।
|
||||
|
||||
मॉड्यूल: trustgraph-flow/trustgraph/storage/objects/cassandra
|
||||
|
||||
5. **स्ट्रक्चर्ड क्वेरी सर्विस** ✅ **[पूर्ण]**
|
||||
परिभाषित प्रारूपों में संरचित क्वेरी स्वीकार करता है।
|
||||
संरचित स्टोर के खिलाफ क्वेरी निष्पादित करता है।
|
||||
क्वेरी मानदंडों से मेल खाने वाले ऑब्जेक्ट लौटाता है।
|
||||
पेजिंग और परिणाम फ़िल्टरिंग का समर्थन करता है।
|
||||
|
||||
मॉड्यूल: trustgraph-flow/trustgraph/query/objects/cassandra
|
||||
|
||||
6. **एजेंट टूल इंटीग्रेशन**:
|
||||
एजेंट फ्रेमवर्क के लिए एक नया टूल क्लास।
|
||||
एजेंटों को संरचित डेटा स्टोर से क्वेरी करने में सक्षम बनाता है।
|
||||
प्राकृतिक भाषा और संरचित क्वेरी इंटरफेस प्रदान करता है।
|
||||
मौजूदा एजेंट निर्णय लेने की प्रक्रियाओं के साथ एकीकृत होता है।
|
||||
|
||||
7. **स्ट्रक्चर्ड डेटा इंजेक्शन सर्विस**:
|
||||
कई प्रारूपों (JSON, CSV, XML) में संरचित डेटा स्वीकार करता है।
|
||||
परिभाषित स्कीमा के खिलाफ आने वाले डेटा को पार्स और सत्यापित करता है।
|
||||
डेटा को सामान्यीकृत ऑब्जेक्ट स्ट्रीम में परिवर्तित करता है।
|
||||
प्रसंस्करण के लिए उपयुक्त संदेश कतारों में ऑब्जेक्ट उत्सर्जित करता है।
|
||||
बल्क अपलोड और स्ट्रीमिंग इंजेक्शन का समर्थन करता है।
|
||||
|
||||
मॉड्यूल: trustgraph-flow/trustgraph/decoding/structured
|
||||
|
||||
8. **ऑब्जेक्ट एम्बेडिंग सर्विस**:
|
||||
संरचित ऑब्जेक्ट के लिए वेक्टर एम्बेडिंग उत्पन्न करता है।
|
||||
संरचित डेटा में सिमेंटिक खोज को सक्षम करता है।
|
||||
संरचित क्वेरी के साथ सिमेंटिक समानता को मिलाकर हाइब्रिड खोज का समर्थन करता है।
|
||||
मौजूदा वेक्टर स्टोर के साथ एकीकृत होता है।
|
||||
|
||||
मॉड्यूल: trustgraph-flow/trustgraph/embeddings/object_embeddings/qdrant
|
||||
|
||||
### डेटा मॉडल:
|
||||
|
||||
#### स्कीमा स्टोरेज मैकेनिज्म:
|
||||
|
||||
स्कीमा को ट्रस्टग्राफ की कॉन्फ़िगरेशन प्रणाली में निम्नलिखित संरचना का उपयोग करके संग्रहीत किया जाता है:
|
||||
|
||||
**टाइप**: `schema` (सभी संरचित डेटा स्कीमा के लिए एक निश्चित मान)।
|
||||
**की**: स्कीमा का अद्वितीय नाम/पहचानकर्ता (जैसे, `customer_records`, `transaction_log`)।
|
||||
**वैल्यू**: संरचना वाली JSON स्कीमा परिभाषा।
|
||||
|
||||
उदाहरण कॉन्फ़िगरेशन प्रविष्टि:
|
||||
```
|
||||
Type: schema
|
||||
Key: customer_records
|
||||
Value: {
|
||||
"name": "customer_records",
|
||||
"description": "Customer information table",
|
||||
"fields": [
|
||||
{
|
||||
"name": "customer_id",
|
||||
"type": "string",
|
||||
"primary_key": true
|
||||
},
|
||||
{
|
||||
"name": "name",
|
||||
"type": "string",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"name": "email",
|
||||
"type": "string",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"name": "registration_date",
|
||||
"type": "timestamp"
|
||||
},
|
||||
{
|
||||
"name": "status",
|
||||
"type": "string",
|
||||
"enum": ["active", "inactive", "suspended"]
|
||||
}
|
||||
],
|
||||
"indexes": ["email", "registration_date"]
|
||||
}
|
||||
```
|
||||
|
||||
यह दृष्टिकोण निम्नलिखित कार्य करने की अनुमति देता है:
|
||||
कोड में बदलाव किए बिना गतिशील स्कीमा परिभाषा
|
||||
आसान स्कीमा अपडेट और संस्करण
|
||||
मौजूदा ट्रस्टग्राफ कॉन्फ़िगरेशन प्रबंधन के साथ सुसंगत एकीकरण
|
||||
एक ही परिनियोजन में एकाधिक स्कीमा के लिए समर्थन
|
||||
|
||||
### एपीआई
|
||||
|
||||
नए एपीआई:
|
||||
ऊपर दिए गए प्रकारों के लिए पल्सर स्कीमा
|
||||
नए फ्लो में पल्सर इंटरफेस
|
||||
फ्लो को यह जानने के लिए कि कौन से
|
||||
स्कीमा प्रकार लोड करने हैं, फ्लो में स्कीमा प्रकारों को निर्दिष्ट करने का एक तरीका आवश्यक है।
|
||||
गेटवे और रिव-गेटवे में जोड़े गए एपीआई
|
||||
|
||||
संशोधित एपीआई:
|
||||
नॉलेज एक्सट्रैक्शन एंडपॉइंट - संरचित ऑब्जेक्ट आउटपुट विकल्प जोड़ें
|
||||
एजेंट एंडपॉइंट - संरचित डेटा टूल समर्थन जोड़ें
|
||||
|
||||
### कार्यान्वयन विवरण
|
||||
|
||||
मौजूदा सम्मेलनों का पालन करें - ये केवल नए प्रोसेसिंग मॉड्यूल हैं।
|
||||
सब कुछ ट्रस्टग्राफ-फ्लो पैकेजों में है, सिवाय ट्रस्टग्राफ-बेस में स्कीमा आइटम के।
|
||||
|
||||
|
||||
इस क्षमता का प्रदर्शन/पायलट करने के लिए वर्कबेंच में कुछ यूआई कार्य की आवश्यकता है।
|
||||
|
||||
|
||||
## सुरक्षा संबंधी विचार
|
||||
|
||||
कोई अतिरिक्त विचार नहीं।
|
||||
|
||||
## प्रदर्शन संबंधी विचार
|
||||
|
||||
कैसेंड्रा प्रश्नों और इंडेक्स का उपयोग करने के बारे में कुछ प्रश्न हैं ताकि प्रश्न धीमे न हों।
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
मौजूदा परीक्षण रणनीति का उपयोग करें, यूनिट, कॉन्ट्रैक्ट और एकीकरण परीक्षण बनाए जाएंगे।
|
||||
|
||||
## माइग्रेशन योजना
|
||||
|
||||
कोई नहीं।
|
||||
|
||||
## समयरेखा
|
||||
|
||||
निर्दिष्ट नहीं है।
|
||||
|
||||
## खुले प्रश्न
|
||||
|
||||
|
||||
क्या इसे अन्य स्टोर प्रकारों के साथ काम करने के लिए बनाया जा सकता है? हम इंटरफेस का उपयोग करने का लक्ष्य रख रहे हैं जो एक स्टोर के साथ काम करने वाले मॉड्यूल को अन्य स्टोर पर लागू करने योग्य बनाते हैं।
|
||||
|
||||
## संदर्भ
|
||||
|
||||
लागू नहीं।
|
||||
281
docs/tech-specs/hi/structured-diag-service.hi.md
Normal file
281
docs/tech-specs/hi/structured-diag-service.hi.md
Normal file
|
|
@ -0,0 +1,281 @@
|
|||
---
|
||||
layout: default
|
||||
title: "स्ट्रक्चर्ड डेटा डायग्नोस्टिक सर्विस टेक्निकल स्पेसिफिकेशन"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# स्ट्रक्चर्ड डेटा डायग्नोस्टिक सर्विस टेक्निकल स्पेसिफिकेशन
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह स्पेसिफिकेशन ट्रस्टग्राफ के भीतर संरचित डेटा का निदान और विश्लेषण करने के लिए एक नए इनवोकेबल सर्विस का वर्णन करता है। यह सर्विस मौजूदा `tg-load-structured-data` कमांड-लाइन टूल से कार्यक्षमता निकालती है और इसे एक अनुरोध/प्रतिक्रिया सेवा के रूप में प्रस्तुत करती है, जिससे डेटा प्रकार का पता लगाने और विवरण पीढ़ी क्षमताओं तक प्रोग्रामेटिक पहुंच सक्षम होती है।
|
||||
|
||||
यह सेवा तीन प्राथमिक कार्यों का समर्थन करती है:
|
||||
|
||||
1. **डेटा टाइप डिटेक्शन**: यह निर्धारित करने के लिए कि इसका प्रारूप क्या है (CSV, JSON, या XML), एक डेटा नमूने का विश्लेषण करें।
|
||||
2. **डिस्क्रिप्टर जेनरेशन**: दिए गए डेटा नमूने और प्रकार के लिए एक ट्रस्टग्राफ संरचित डेटा विवरण उत्पन्न करें।
|
||||
3. **संयुक्त निदान**: अनुक्रम में डेटा प्रकार का पता लगाने और विवरण पीढ़ी दोनों करें।
|
||||
|
||||
## लक्ष्य
|
||||
|
||||
**डेटा विश्लेषण का मॉड्यूलरकरण**: CLI से डेटा निदान तर्क को पुन: प्रयोज्य सेवा घटकों में निकालें।
|
||||
**प्रोग्रामेटिक एक्सेस सक्षम करें**: डेटा विश्लेषण क्षमताओं तक API-आधारित पहुंच प्रदान करें।
|
||||
**एकाधिक डेटा प्रारूपों का समर्थन करें**: CSV, JSON और XML डेटा प्रारूपों को लगातार संभालें।
|
||||
**सटीक विवरण उत्पन्न करें**: संरचित डेटा विवरण उत्पन्न करें जो स्रोत डेटा को ट्रस्टग्राफ स्कीमा से सटीक रूप से मैप करते हैं।
|
||||
**पिछला संगतता बनाए रखें**: सुनिश्चित करें कि मौजूदा CLI कार्यक्षमता जारी रहती है।
|
||||
**सेवा रचना को सक्षम करें**: अन्य सेवाओं को डेटा निदान क्षमताओं का लाभ उठाने दें।
|
||||
**परीक्षण क्षमता में सुधार करें**: बेहतर परीक्षण के लिए CLI इंटरफ़ेस से व्यावसायिक तर्क को अलग करें।
|
||||
**स्ट्रीमिंग विश्लेषण का समर्थन करें**: संपूर्ण फ़ाइलों को लोड किए बिना डेटा नमूनों का विश्लेषण सक्षम करें।
|
||||
|
||||
## पृष्ठभूमि
|
||||
|
||||
वर्तमान में, `tg-load-structured-data` कमांड संरचित डेटा का विश्लेषण करने और विवरण उत्पन्न करने के लिए व्यापक कार्यक्षमता प्रदान करता है। हालाँकि, यह कार्यक्षमता CLI इंटरफ़ेस से दृढ़ता से जुड़ी हुई है, जो इसकी पुन: प्रयोज्यता को सीमित करती है।
|
||||
|
||||
वर्तमान सीमाएँ शामिल हैं:
|
||||
CLI कोड में एम्बेडेड डेटा निदान तर्क।
|
||||
डेटा प्रकार का पता लगाने और विवरण पीढ़ी तक कोई प्रोग्रामेटिक पहुंच नहीं।
|
||||
अन्य सेवाओं में निदान क्षमताओं को एकीकृत करना मुश्किल है।
|
||||
डेटा विश्लेषण वर्कफ़्लो को संयोजित करने की सीमित क्षमता।
|
||||
|
||||
यह स्पेसिफिकेशन इन कमियों को एक समर्पित संरचित डेटा निदान सेवा बनाकर संबोधित करता है। इन क्षमताओं को एक सेवा के रूप में उजागर करके, ट्रस्टग्राफ:
|
||||
अन्य सेवाओं को डेटा का प्रोग्रामेटिक रूप से विश्लेषण करने में सक्षम बनाता है।
|
||||
अधिक जटिल डेटा प्रसंस्करण पाइपलाइन का समर्थन करता है।
|
||||
बाहरी प्रणालियों के साथ एकीकरण को सुविधाजनक बनाता है।
|
||||
चिंताओं के अलगाव के माध्यम से रखरखाव में सुधार करता है।
|
||||
|
||||
## तकनीकी डिजाइन
|
||||
|
||||
### आर्किटेक्चर
|
||||
|
||||
संरचित डेटा निदान सेवा के लिए निम्नलिखित तकनीकी घटकों की आवश्यकता होती है:
|
||||
|
||||
1. **डायग्नोस्टिक सर्विस प्रोसेसर**
|
||||
आने वाले निदान अनुरोधों को संभालता है।
|
||||
डेटा प्रकार का पता लगाने और विवरण पीढ़ी का समन्वय करता है।
|
||||
निदान परिणामों के साथ संरचित प्रतिक्रियाएँ लौटाता है।
|
||||
|
||||
मॉड्यूल: `trustgraph-flow/trustgraph/diagnosis/structured_data/service.py`
|
||||
|
||||
2. **डेटा टाइप डिटेक्टर**
|
||||
डेटा प्रारूप (CSV, JSON, XML) की पहचान करने के लिए एल्गोरिथम का उपयोग करता है।
|
||||
पता लगाए गए प्रारूप और आत्मविश्वास स्कोर लौटाता है।
|
||||
पता लगाए गए प्रारूप और आत्मविश्वास स्कोर वापस करता है।
|
||||
|
||||
मॉड्यूल: `trustgraph-flow/trustgraph/diagnosis/structured_data/type_detector.py`
|
||||
|
||||
3. **डिस्क्रिप्टर जेनरेटर**
|
||||
विवरण उत्पन्न करने के लिए प्रॉम्प्ट सेवा का उपयोग करता है।
|
||||
प्रारूप-विशिष्ट प्रॉम्प्ट (diagnose-csv, diagnose-json, diagnose-xml) को लागू करता है।
|
||||
डेटा फ़ील्ड को प्रॉम्प्ट प्रतिक्रियाओं के माध्यम से ट्रस्टग्राफ स्कीमा फ़ील्ड में मैप करता है।
|
||||
|
||||
मॉड्यूल: `trustgraph-flow/trustgraph/diagnosis/structured_data/descriptor_generator.py`
|
||||
|
||||
### डेटा मॉडल
|
||||
|
||||
#### StructuredDataDiagnosisRequest
|
||||
|
||||
संरचित डेटा निदान कार्यों के लिए अनुरोध संदेश:
|
||||
|
||||
```python
|
||||
class StructuredDataDiagnosisRequest:
|
||||
operation: str # "detect-type", "generate-descriptor", or "diagnose"
|
||||
sample: str # Data sample to analyze (text content)
|
||||
type: Optional[str] # Data type (csv, json, xml) - required for generate-descriptor
|
||||
schema_name: Optional[str] # Target schema name for descriptor generation
|
||||
options: Dict[str, Any] # Additional options (e.g., delimiter for CSV)
|
||||
```
|
||||
|
||||
#### संरचित डेटा निदान प्रतिक्रिया
|
||||
|
||||
निदान परिणामों को शामिल करने वाला प्रतिक्रिया संदेश:
|
||||
|
||||
```python
|
||||
class StructuredDataDiagnosisResponse:
|
||||
operation: str # The operation that was performed
|
||||
detected_type: Optional[str] # Detected data type (for detect-type/diagnose)
|
||||
confidence: Optional[float] # Confidence score for type detection
|
||||
descriptor: Optional[Dict] # Generated descriptor (for generate-descriptor/diagnose)
|
||||
error: Optional[str] # Error message if operation failed
|
||||
metadata: Dict[str, Any] # Additional metadata (e.g., field count, sample records)
|
||||
```
|
||||
|
||||
#### विवरण संरचना
|
||||
|
||||
उत्पन्न विवरण मौजूदा संरचित डेटा विवरण प्रारूप का पालन करता है:
|
||||
|
||||
```json
|
||||
{
|
||||
"format": {
|
||||
"type": "csv",
|
||||
"encoding": "utf-8",
|
||||
"options": {
|
||||
"delimiter": ",",
|
||||
"has_header": true
|
||||
}
|
||||
},
|
||||
"mappings": [
|
||||
{
|
||||
"source_field": "customer_id",
|
||||
"target_field": "id",
|
||||
"transforms": [
|
||||
{"type": "trim"}
|
||||
]
|
||||
}
|
||||
],
|
||||
"output": {
|
||||
"schema_name": "customer",
|
||||
"options": {
|
||||
"batch_size": 1000,
|
||||
"confidence": 0.9
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### सेवा इंटरफ़ेस
|
||||
|
||||
यह सेवा अनुरोध/प्रतिक्रिया पैटर्न के माध्यम से निम्नलिखित कार्यों को प्रदान करेगी:
|
||||
|
||||
1. **टाइप डिटेक्शन ऑपरेशन**
|
||||
इनपुट: डेटा नमूना
|
||||
प्रसंस्करण: एल्गोरिथम डिटेक्शन का उपयोग करके डेटा संरचना का विश्लेषण करें
|
||||
आउटपुट: पता लगाए गए प्रकार के साथ आत्मविश्वास स्कोर
|
||||
|
||||
2. **डिस्क्रिप्टर जनरेशन ऑपरेशन**
|
||||
इनपुट: डेटा नमूना, प्रकार, लक्षित स्कीमा नाम
|
||||
प्रसंस्करण:
|
||||
प्रारूप-विशिष्ट प्रॉम्प्ट आईडी (diagnose-csv, diagnose-json, या diagnose-xml) के साथ प्रॉम्प्ट सेवा को कॉल करें
|
||||
डेटा नमूना और उपलब्ध स्कीमा को प्रॉम्प्ट में पास करें
|
||||
प्रॉम्प्ट प्रतिक्रिया से उत्पन्न डिस्क्रिप्टर प्राप्त करें
|
||||
आउटपुट: संरचित डेटा डिस्क्रिप्टर
|
||||
|
||||
3. **संयुक्त निदान ऑपरेशन**
|
||||
इनपुट: डेटा नमूना, वैकल्पिक स्कीमा नाम
|
||||
प्रसंस्करण:
|
||||
पहले एल्गोरिथम डिटेक्शन का उपयोग करके प्रारूप की पहचान करें
|
||||
पता लगाए गए प्रकार के आधार पर उपयुक्त प्रारूप-विशिष्ट प्रॉम्प्ट का चयन करें
|
||||
डिस्क्रिप्टर उत्पन्न करने के लिए प्रॉम्प्ट सेवा को कॉल करें
|
||||
आउटपुट: पता लगाए गए प्रकार और डिस्क्रिप्टर दोनों
|
||||
|
||||
### कार्यान्वयन विवरण
|
||||
|
||||
यह सेवा TrustGraph सेवा सम्मेलनों का पालन करेगी:
|
||||
|
||||
1. **सेवा पंजीकरण**
|
||||
`structured-diag` सेवा प्रकार के रूप में पंजीकृत करें
|
||||
मानक अनुरोध/प्रतिक्रिया विषयों का उपयोग करें
|
||||
FlowProcessor बेस क्लास को लागू करें
|
||||
प्रॉम्प्ट सेवा के साथ इंटरैक्शन के लिए PromptClientSpec को पंजीकृत करें
|
||||
|
||||
2. **कॉन्फ़िगरेशन प्रबंधन**
|
||||
कॉन्फ़िग सेवा के माध्यम से स्कीमा कॉन्फ़िगरेशन तक पहुंचें
|
||||
प्रदर्शन के लिए स्कीमा को कैश करें
|
||||
गतिशील रूप से कॉन्फ़िगरेशन अपडेट को संभालें
|
||||
|
||||
3. **प्रॉम्प्ट एकीकरण**
|
||||
मौजूदा प्रॉम्प्ट सेवा बुनियादी ढांचे का उपयोग करें
|
||||
प्रारूप-विशिष्ट प्रॉम्प्ट आईडी के साथ प्रॉम्प्ट सेवा को कॉल करें:
|
||||
`diagnose-csv`: CSV डेटा विश्लेषण के लिए
|
||||
`diagnose-json`: JSON डेटा विश्लेषण के लिए
|
||||
`diagnose-xml`: XML डेटा विश्लेषण के लिए
|
||||
प्रॉम्प्ट सेवा में कॉन्फ़िगर किए गए हैं, सेवा में हार्ड-कोडेड नहीं हैं
|
||||
स्कीमा और डेटा नमूने को प्रॉम्प्ट चर के रूप में पास करें
|
||||
डिस्क्रिप्टर निकालने के लिए प्रॉम्प्ट प्रतिक्रियाओं को पार्स करें
|
||||
|
||||
4. **त्रुटि प्रबंधन**
|
||||
इनपुट डेटा नमूनों को मान्य करें
|
||||
वर्णनात्मक त्रुटि संदेश प्रदान करें
|
||||
खराब डेटा को शालीनता से संभालें
|
||||
प्रॉम्प्ट सेवा विफलताओं को संभालें
|
||||
|
||||
5. **डेटा नमूनाकरण**
|
||||
कॉन्फ़िगर करने योग्य नमूना आकारों को संसाधित करें
|
||||
अधूरी रिकॉर्ड को उचित रूप से संभालें
|
||||
नमूनाकरण स्थिरता बनाए रखें
|
||||
|
||||
### एपीआई एकीकरण
|
||||
|
||||
यह सेवा मौजूदा TrustGraph एपीआई के साथ एकीकृत होगी:
|
||||
|
||||
संशोधित घटक:
|
||||
`tg-load-structured-data` CLI - निदान कार्यों के लिए नई सेवा का उपयोग करने के लिए रिफैक्टर किया गया
|
||||
फ्लो एपीआई - संरचित डेटा निदान अनुरोधों का समर्थन करने के लिए विस्तारित
|
||||
|
||||
नए सेवा एंडपॉइंट:
|
||||
`/api/v1/flow/{flow}/diagnose/structured-data` - निदान अनुरोधों के लिए वेबसॉकेट एंडपॉइंट
|
||||
`/api/v1/diagnose/structured-data` - सिंक्रोनस निदान के लिए REST एंडपॉइंट
|
||||
|
||||
### संदेश प्रवाह
|
||||
|
||||
```
|
||||
Client → Gateway → Structured Diag Service → Config Service (for schemas)
|
||||
↓
|
||||
Type Detector (algorithmic)
|
||||
↓
|
||||
Prompt Service (diagnose-csv/json/xml)
|
||||
↓
|
||||
Descriptor Generator (parses prompt response)
|
||||
↓
|
||||
Client ← Gateway ← Structured Diag Service (response)
|
||||
```
|
||||
|
||||
## सुरक्षा संबंधी विचार
|
||||
|
||||
इंजेक्शन हमलों को रोकने के लिए इनपुट सत्यापन
|
||||
DoS को रोकने के लिए डेटा नमूनों पर आकार सीमाएं
|
||||
उत्पन्न विवरणों का सैनिटाइजेशन
|
||||
मौजूदा ट्रस्टग्राफ प्रमाणीकरण के माध्यम से एक्सेस नियंत्रण
|
||||
|
||||
## प्रदर्शन संबंधी विचार
|
||||
|
||||
कॉन्फ़िगरेशन सेवा कॉल को कम करने के लिए स्कीमा परिभाषाओं को कैश करें
|
||||
उत्तरदायी प्रदर्शन बनाए रखने के लिए नमूना आकारों को सीमित करें
|
||||
बड़े डेटा नमूनों के लिए स्ट्रीमिंग प्रोसेसिंग का उपयोग करें
|
||||
लंबे समय तक चलने वाले विश्लेषणों के लिए टाइमआउट तंत्र लागू करें
|
||||
|
||||
## परीक्षण रणनीति
|
||||
|
||||
1. **इकाई परीक्षण**
|
||||
विभिन्न डेटा प्रारूपों के लिए प्रकार का पता लगाना
|
||||
विवरण पीढ़ी की सटीकता
|
||||
त्रुटि हैंडलिंग परिदृश्य
|
||||
|
||||
2. **एकीकरण परीक्षण**
|
||||
सेवा अनुरोध/प्रतिक्रिया प्रवाह
|
||||
स्कीमा पुनर्प्राप्ति और कैशिंग
|
||||
CLI एकीकरण
|
||||
|
||||
3. **प्रदर्शन परीक्षण**
|
||||
बड़े नमूने प्रसंस्करण
|
||||
समवर्ती अनुरोध हैंडलिंग
|
||||
लोड के तहत मेमोरी उपयोग
|
||||
|
||||
## माइग्रेशन योजना
|
||||
|
||||
1. **चरण 1**: मुख्य कार्यक्षमता के साथ सेवा लागू करें
|
||||
2. **चरण 2**: CLI को सेवा का उपयोग करने के लिए रिफैक्टर करें (पिछड़ी संगतता बनाए रखें)
|
||||
3. **चरण 3**: REST API एंडपॉइंट जोड़ें
|
||||
4. **चरण 4**: एम्बेडेड CLI लॉजिक को अप्रचलित करें (सूचना अवधि के साथ)
|
||||
|
||||
## समयरेखा
|
||||
|
||||
सप्ताह 1-2: मुख्य सेवा और प्रकार का पता लगाना लागू करें
|
||||
सप्ताह 3-4: विवरण पीढ़ी और एकीकरण जोड़ें
|
||||
सप्ताह 5: परीक्षण और दस्तावेज़ीकरण
|
||||
सप्ताह 6: CLI रिफैक्टरिंग और माइग्रेशन
|
||||
|
||||
## खुले प्रश्न
|
||||
|
||||
क्या सेवा को अतिरिक्त डेटा प्रारूपों (जैसे, Parquet, Avro) का समर्थन करना चाहिए?
|
||||
विश्लेषण के लिए अधिकतम नमूना आकार क्या होना चाहिए?
|
||||
क्या निदान परिणाम बार-बार अनुरोधों के लिए कैश किए जाने चाहिए?
|
||||
सेवा को मल्टी-स्कीमा परिदृश्यों को कैसे संभालना चाहिए?
|
||||
क्या प्रॉम्प्ट आईडी सेवा के लिए कॉन्फ़िगर करने योग्य पैरामीटर होने चाहिए?
|
||||
|
||||
## संदर्भ
|
||||
|
||||
[स्ट्रक्चर्ड डेटा डिस्क्रिप्टर विनिर्देश](structured-data-descriptor.md)
|
||||
[स्ट्रक्चर्ड डेटा लोडिंग दस्तावेज़](structured-data.md)
|
||||
`tg-load-structured-data` कार्यान्वयन: `trustgraph-cli/trustgraph/cli/load_structured_data.py`
|
||||
499
docs/tech-specs/hi/tool-group.hi.md
Normal file
499
docs/tech-specs/hi/tool-group.hi.md
Normal file
|
|
@ -0,0 +1,499 @@
|
|||
---
|
||||
layout: default
|
||||
title: "ट्रस्टग्राफ टूल ग्रुप सिस्टम"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# ट्रस्टग्राफ टूल ग्रुप सिस्टम
|
||||
|
||||
> **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.
|
||||
## तकनीकी विनिर्देश v1.0
|
||||
|
||||
### कार्यकारी सारांश
|
||||
|
||||
यह विनिर्देश ट्रस्टग्राफ एजेंटों के लिए एक टूल ग्रुपिंग सिस्टम को परिभाषित करता है जो विशिष्ट अनुरोधों के लिए कौन से टूल उपलब्ध हैं, इस पर बारीक नियंत्रण की अनुमति देता है। यह सिस्टम कॉन्फ़िगरेशन और अनुरोध-स्तरीय विनिर्देश के माध्यम से समूह-आधारित टूल फ़िल्टरिंग पेश करता है, जो एजेंट क्षमताओं के बेहतर सुरक्षा सीमाओं, संसाधन प्रबंधन और कार्यात्मक विभाजन को सक्षम करता है।
|
||||
|
||||
### 1. अवलोकन
|
||||
|
||||
#### 1.1 समस्या विवरण
|
||||
|
||||
वर्तमान में, ट्रस्टग्राफ एजेंटों के पास अनुरोध संदर्भ या सुरक्षा आवश्यकताओं की परवाह किए बिना, सभी कॉन्फ़िगर किए गए टूल तक पहुंच होती है। इससे कई चुनौतियाँ उत्पन्न होती हैं:
|
||||
|
||||
**सुरक्षा जोखिम**: संवेदनशील टूल (जैसे, डेटा संशोधन) रीड-ओनली प्रश्नों के लिए भी उपलब्ध हैं
|
||||
**संसाधन बर्बादी**: जटिल टूल लोड किए जाते हैं, भले ही सरल प्रश्नों के लिए उनकी आवश्यकता न हो
|
||||
**कार्यात्मक भ्रम**: एजेंट उपयुक्त टूल का चयन कर सकते हैं जब सरल विकल्प मौजूद हों
|
||||
**मल्टी-टेनेन्ट अलगाव**: विभिन्न उपयोगकर्ता समूहों को अलग-अलग टूल सेट तक पहुंचने की आवश्यकता होती है
|
||||
|
||||
#### 1.2 समाधान अवलोकन
|
||||
|
||||
टूल ग्रुप सिस्टम निम्नलिखित पेश करता है:
|
||||
|
||||
1. **समूह वर्गीकरण**: टूल को कॉन्फ़िगरेशन के दौरान समूह सदस्यता के साथ टैग किया जाता है
|
||||
2. **अनुरोध-स्तरीय फ़िल्टरिंग**: AgentRequest निर्दिष्ट करता है कि कौन से टूल समूह अनुमत हैं
|
||||
3. **रनटाइम प्रवर्तन**: एजेंटों के पास केवल अनुरोधित समूहों से मेल खाने वाले टूल तक पहुंच होती है
|
||||
4. **लचीला समूहीकरण**: जटिल परिदृश्यों के लिए टूल कई समूहों से संबंधित हो सकते हैं
|
||||
|
||||
### 2. स्कीमा परिवर्तन
|
||||
|
||||
#### 2.1 टूल कॉन्फ़िगरेशन स्कीमा संवर्धन
|
||||
|
||||
मौजूदा टूल कॉन्फ़िगरेशन को एक `group` फ़ील्ड के साथ बढ़ाया गया है:
|
||||
|
||||
**पहले:**
|
||||
```json
|
||||
{
|
||||
"name": "knowledge-query",
|
||||
"type": "knowledge-query",
|
||||
"description": "Query the knowledge graph"
|
||||
}
|
||||
```
|
||||
|
||||
**इसके बाद:**
|
||||
```json
|
||||
{
|
||||
"name": "knowledge-query",
|
||||
"type": "knowledge-query",
|
||||
"description": "Query the knowledge graph",
|
||||
"group": ["read-only", "knowledge", "basic"]
|
||||
}
|
||||
```
|
||||
|
||||
**समूह क्षेत्र विनिर्देश:**
|
||||
`group`: Array(String) - यह सूची उन समूहों की है जिनसे यह उपकरण संबंधित है।
|
||||
**वैकल्पिक**: जिन उपकरणों में समूह क्षेत्र नहीं है, वे "डिफ़ॉल्ट" समूह से संबंधित होते हैं।
|
||||
**बहु-सदस्यता**: उपकरण कई समूहों से संबंधित हो सकते हैं।
|
||||
**केस-संवेदी**: समूह नाम सटीक स्ट्रिंग मिलान होते हैं।
|
||||
|
||||
#### 2.1.2 उपकरण स्थिति परिवर्तन संवर्धन
|
||||
|
||||
उपकरण वैकल्पिक रूप से स्थिति परिवर्तनों और स्थिति-आधारित उपलब्धता को निर्दिष्ट कर सकते हैं:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "knowledge-query",
|
||||
"type": "knowledge-query",
|
||||
"description": "Query the knowledge graph",
|
||||
"group": ["read-only", "knowledge", "basic"],
|
||||
"state": "analysis",
|
||||
"available_in_states": ["undefined", "research"]
|
||||
}
|
||||
```
|
||||
|
||||
**राज्य क्षेत्र विनिर्देश:**
|
||||
`state`: स्ट्रिंग - **वैकल्पिक** - सफल टूल निष्पादन के बाद जाने वाला राज्य
|
||||
`available_in_states`: Array(String) - **वैकल्पिक** - उन राज्यों में जहां यह टूल उपलब्ध है
|
||||
**डिफ़ॉल्ट व्यवहार:** `available_in_states` के बिना टूल सभी राज्यों में उपलब्ध होते हैं
|
||||
**राज्य परिवर्तन:** केवल सफल टूल निष्पादन के बाद होता है
|
||||
|
||||
#### 2.2 AgentRequest स्कीमा में सुधार
|
||||
|
||||
`trustgraph-base/trustgraph/schema/services/agent.py` में `AgentRequest` स्कीमा में सुधार किया गया है:
|
||||
|
||||
**वर्तमान AgentRequest:**
|
||||
`question`: स्ट्रिंग - उपयोगकर्ता प्रश्न
|
||||
`plan`: स्ट्रिंग - निष्पादन योजना (हटाया जा सकता है)
|
||||
`state`: स्ट्रिंग - एजेंट राज्य
|
||||
`history`: Array(AgentStep) - निष्पादन इतिहास
|
||||
|
||||
**सुधारे गए AgentRequest:**
|
||||
`question`: स्ट्रिंग - उपयोगकर्ता प्रश्न
|
||||
`state`: स्ट्रिंग - एजेंट निष्पादन स्थिति (अब सक्रिय रूप से टूल फ़िल्टरिंग के लिए उपयोग किया जाता है)
|
||||
`history`: Array(AgentStep) - निष्पादन इतिहास
|
||||
`group`: Array(String) - **नया** - इस अनुरोध के लिए अनुमत टूल समूह
|
||||
|
||||
**स्कीमा परिवर्तन:**
|
||||
**हटाया गया:** `plan` फ़ील्ड अब आवश्यक नहीं है और इसे हटाया जा सकता है (मूल रूप से टूल विनिर्देश के लिए अभिप्रेत था)
|
||||
**जोड़ा गया:** टूल समूह विनिर्देश के लिए `group` फ़ील्ड
|
||||
**सुधारा गया:** `state` फ़ील्ड अब निष्पादन के दौरान टूल उपलब्धता को नियंत्रित करता है
|
||||
|
||||
**फ़ील्ड व्यवहार:**
|
||||
|
||||
**समूह फ़ील्ड:**
|
||||
**वैकल्पिक:** यदि निर्दिष्ट नहीं है, तो डिफ़ॉल्ट रूप से ["default"] होता है
|
||||
**प्रतिच्छेदन:** केवल वे टूल जो कम से कम एक निर्दिष्ट समूह से मेल खाते हैं, वे उपलब्ध हैं
|
||||
**खाली सरणी:** कोई टूल उपलब्ध नहीं है (एजेंट केवल आंतरिक तर्क का उपयोग कर सकता है)
|
||||
**वाइल्डकार्ड:** विशेष समूह "*" सभी टूल तक पहुंच प्रदान करता है
|
||||
|
||||
**राज्य फ़ील्ड:**
|
||||
**वैकल्पिक:** यदि निर्दिष्ट नहीं है, तो डिफ़ॉल्ट रूप से "अपरिभाषित" होता है
|
||||
**राज्य-आधारित फ़िल्टरिंग:** केवल वर्तमान राज्य में उपलब्ध टूल ही पात्र हैं
|
||||
**डिफ़ॉल्ट राज्य:** "अपरिभाषित" राज्य सभी टूल की अनुमति देता है (समूह फ़िल्टरिंग के अधीन)
|
||||
**राज्य परिवर्तन:** सफल निष्पादन के बाद टूल अपनी स्थिति बदल सकते हैं
|
||||
|
||||
### 3. कस्टम समूह उदाहरण
|
||||
|
||||
संगठन डोमेन-विशिष्ट समूह परिभाषित कर सकते हैं:
|
||||
|
||||
```json
|
||||
{
|
||||
"financial-tools": ["stock-query", "portfolio-analysis"],
|
||||
"medical-tools": ["diagnosis-assist", "drug-interaction"],
|
||||
"legal-tools": ["contract-analysis", "case-search"]
|
||||
}
|
||||
```
|
||||
|
||||
### 4. कार्यान्वयन विवरण
|
||||
|
||||
#### 4.1 टूल लोडिंग और फ़िल्टरिंग
|
||||
|
||||
**कॉन्फ़िगरेशन चरण:**
|
||||
1. सभी टूल अपने समूह असाइनमेंट के साथ कॉन्फ़िगरेशन से लोड किए जाते हैं।
|
||||
2. स्पष्ट समूहों के बिना टूल को "डिफ़ॉल्ट" समूह में असाइन किया जाता है।
|
||||
3. समूह सदस्यता को मान्य किया जाता है और टूल रजिस्ट्री में संग्रहीत किया जाता है।
|
||||
|
||||
**अनुरोध प्रसंस्करण चरण:**
|
||||
1. एजेंट अनुरोध वैकल्पिक समूह विनिर्देश के साथ आता है।
|
||||
2. एजेंट उपलब्ध टूल को समूह प्रतिच्छेदन के आधार पर फ़िल्टर करता है।
|
||||
3. केवल मिलान करने वाले टूल को एजेंट निष्पादन संदर्भ में पास किया जाता है।
|
||||
4. एजेंट अनुरोध जीवनचक्र के दौरान फ़िल्टर किए गए टूल सेट के साथ काम करता है।
|
||||
|
||||
#### 4.2 टूल फ़िल्टरिंग लॉजिक
|
||||
|
||||
**संयुक्त समूह और स्थिति फ़िल्टरिंग:**
|
||||
|
||||
```
|
||||
For each configured tool:
|
||||
tool_groups = tool.group || ["default"]
|
||||
tool_states = tool.available_in_states || ["*"] // Available in all states
|
||||
|
||||
For each request:
|
||||
requested_groups = request.group || ["default"]
|
||||
current_state = request.state || "undefined"
|
||||
|
||||
Tool is available if:
|
||||
// Group filtering
|
||||
(intersection(tool_groups, requested_groups) is not empty OR "*" in requested_groups)
|
||||
AND
|
||||
// State filtering
|
||||
(current_state in tool_states OR "*" in tool_states)
|
||||
```
|
||||
|
||||
**राज्य परिवर्तन तर्क:**
|
||||
|
||||
```
|
||||
After successful tool execution:
|
||||
if tool.state is defined:
|
||||
next_request.state = tool.state
|
||||
else:
|
||||
next_request.state = current_request.state // No change
|
||||
```
|
||||
|
||||
#### 4.3 एजेंट एकीकरण बिंदु
|
||||
|
||||
**ReAct एजेंट:**
|
||||
टूल फ़िल्टरिंग एजेंट_मैनेजर.py में टूल रजिस्ट्री निर्माण के दौरान होती है।
|
||||
उपलब्ध टूल की सूची को योजना निर्माण से पहले समूह और स्थिति दोनों द्वारा फ़िल्टर किया जाता है।
|
||||
स्थिति परिवर्तन सफल टूल निष्पादन के बाद AgentRequest.state फ़ील्ड को अपडेट करते हैं।
|
||||
अगले पुनरावृत्ति में टूल फ़िल्टरिंग के लिए अपडेट की गई स्थिति का उपयोग किया जाता है।
|
||||
|
||||
**विश्वास-आधारित एजेंट:**
|
||||
टूल फ़िल्टरिंग योजना निर्माण के दौरान प्लानर.py में होती है।
|
||||
ExecutionStep सत्यापन यह सुनिश्चित करता है कि केवल समूह+स्थिति के लिए योग्य टूल का उपयोग किया जाए।
|
||||
फ्लो कंट्रोलर रनटाइम पर टूल की उपलब्धता को लागू करता है।
|
||||
चरणों के बीच फ्लो कंट्रोलर द्वारा स्थिति परिवर्तन प्रबंधित किए जाते हैं।
|
||||
|
||||
### 5. कॉन्फ़िगरेशन उदाहरण
|
||||
|
||||
#### 5.1 समूहों और स्थितियों के साथ टूल कॉन्फ़िगरेशन
|
||||
|
||||
```yaml
|
||||
tool:
|
||||
knowledge-query:
|
||||
type: knowledge-query
|
||||
name: "Knowledge Graph Query"
|
||||
description: "Query the knowledge graph for entities and relationships"
|
||||
group: ["read-only", "knowledge", "basic"]
|
||||
state: "analysis"
|
||||
available_in_states: ["undefined", "research"]
|
||||
|
||||
graph-update:
|
||||
type: graph-update
|
||||
name: "Graph Update"
|
||||
description: "Add or modify entities in the knowledge graph"
|
||||
group: ["write", "knowledge", "admin"]
|
||||
available_in_states: ["analysis", "modification"]
|
||||
|
||||
text-completion:
|
||||
type: text-completion
|
||||
name: "Text Completion"
|
||||
description: "Generate text using language models"
|
||||
group: ["read-only", "text", "basic"]
|
||||
state: "undefined"
|
||||
# No available_in_states = available in all states
|
||||
|
||||
complex-analysis:
|
||||
type: mcp-tool
|
||||
name: "Complex Analysis Tool"
|
||||
description: "Perform complex data analysis"
|
||||
group: ["advanced", "compute", "expensive"]
|
||||
state: "results"
|
||||
available_in_states: ["analysis"]
|
||||
mcp_tool_id: "analysis-server"
|
||||
|
||||
reset-workflow:
|
||||
type: mcp-tool
|
||||
name: "Reset Workflow"
|
||||
description: "Reset to initial state"
|
||||
group: ["admin"]
|
||||
state: "undefined"
|
||||
available_in_states: ["analysis", "results"]
|
||||
```
|
||||
|
||||
#### 5.2 अनुरोध के उदाहरण राज्य वर्कफ़्लो के साथ
|
||||
|
||||
**प्रारंभिक अनुसंधान अनुरोध:**
|
||||
```json
|
||||
{
|
||||
"question": "What entities are connected to Company X?",
|
||||
"group": ["read-only", "knowledge"],
|
||||
"state": "undefined"
|
||||
}
|
||||
```
|
||||
*उपलब्ध उपकरण: ज्ञान-पूछताछ, पाठ-पूर्णता*
|
||||
*ज्ञान-पूछताछ के बाद: अवस्था → "विश्लेषण"*
|
||||
|
||||
**विश्लेषण चरण:**
|
||||
```json
|
||||
{
|
||||
"question": "Continue analysis based on previous results",
|
||||
"group": ["advanced", "compute", "write"],
|
||||
"state": "analysis"
|
||||
}
|
||||
```
|
||||
*उपलब्ध उपकरण: जटिल-विश्लेषण, ग्राफ-अपडेट, रीसेट-वर्कफ़्लो*
|
||||
*जटिल-विश्लेषण के बाद: अवस्था → "परिणाम"*
|
||||
|
||||
**परिणाम चरण:**
|
||||
```json
|
||||
{
|
||||
"question": "What should I do with these results?",
|
||||
"group": ["admin"],
|
||||
"state": "results"
|
||||
}
|
||||
```
|
||||
*उपलब्ध उपकरण: केवल reset-workflow*
|
||||
*reset-workflow के बाद: स्थिति → "अपरिभाषित"*
|
||||
|
||||
**वर्कफ़्लो उदाहरण - पूर्ण प्रवाह:**
|
||||
1. **शुरुआत (अपरिभाषित):** ज्ञान-पूछताछ का उपयोग करें → "विश्लेषण" में संक्रमण
|
||||
2. **विश्लेषण अवस्था:** जटिल-विश्लेषण का उपयोग करें → "परिणाम" में संक्रमण
|
||||
3. **परिणाम अवस्था:** reset-workflow का उपयोग करें → "अपरिभाषित" में वापस संक्रमण
|
||||
4. **शुरुआत में वापस:** सभी प्रारंभिक उपकरण फिर से उपलब्ध
|
||||
|
||||
### 6. सुरक्षा संबंधी विचार
|
||||
|
||||
#### 6.1 एक्सेस नियंत्रण एकीकरण
|
||||
|
||||
**गेटवे-स्तरीय फ़िल्टरिंग:**
|
||||
गेटवे उपयोगकर्ता अनुमतियों के आधार पर समूह प्रतिबंधों को लागू कर सकता है
|
||||
अनुरोध हेरफेर के माध्यम से विशेषाधिकारों को बढ़ाने से रोकें
|
||||
ऑडिट ट्रेल में अनुरोधित और अनुमत टूल समूह शामिल हैं
|
||||
|
||||
**उदाहरण गेटवे तर्क:**
|
||||
```
|
||||
user_permissions = get_user_permissions(request.user_id)
|
||||
allowed_groups = user_permissions.tool_groups
|
||||
requested_groups = request.group
|
||||
|
||||
# Validate request doesn't exceed permissions
|
||||
if not is_subset(requested_groups, allowed_groups):
|
||||
reject_request("Insufficient permissions for requested tool groups")
|
||||
```
|
||||
|
||||
#### 6.2 ऑडिट और निगरानी
|
||||
|
||||
**बेहतर ऑडिट ट्रेल:**
|
||||
प्रत्येक अनुरोध के लिए अनुरोधित टूल समूहों और प्रारंभिक स्थिति को लॉग करें।
|
||||
समूह सदस्यता द्वारा स्थिति परिवर्तन और टूल उपयोग को ट्रैक करें।
|
||||
अनधिकृत समूह एक्सेस प्रयासों और अमान्य स्थिति परिवर्तनों की निगरानी करें।
|
||||
असामान्य समूह उपयोग पैटर्न या संदिग्ध स्थिति वर्कफ़्लो पर अलर्ट जारी करें।
|
||||
|
||||
### 7. माइग्रेशन रणनीति
|
||||
|
||||
#### 7.1 पिछड़ा संगतता
|
||||
|
||||
**चरण 1: अतिरिक्त परिवर्तन**
|
||||
टूल कॉन्फ़िगरेशन में वैकल्पिक `group` फ़ील्ड जोड़ें।
|
||||
AgentRequest स्कीमा में वैकल्पिक `group` फ़ील्ड जोड़ें।
|
||||
डिफ़ॉल्ट व्यवहार: सभी मौजूदा टूल "डिफ़ॉल्ट" समूह से संबंधित हैं।
|
||||
समूह फ़ील्ड के बिना मौजूदा अनुरोध "डिफ़ॉल्ट" समूह का उपयोग करते हैं।
|
||||
|
||||
**मौजूदा व्यवहार संरक्षित:**
|
||||
समूह कॉन्फ़िगरेशन के बिना टूल काम करना जारी रखते हैं (डिफ़ॉल्ट समूह)।
|
||||
स्थिति कॉन्फ़िगरेशन के बिना टूल सभी स्थितियों में उपलब्ध हैं।
|
||||
समूह विनिर्देश के बिना अनुरोध सभी टूल तक पहुंचते हैं (डिफ़ॉल्ट समूह)।
|
||||
स्थिति विनिर्देश के बिना अनुरोध "अपरिभाषित" स्थिति का उपयोग करते हैं (सभी टूल उपलब्ध हैं)।
|
||||
मौजूदा परिनियोजन में कोई ब्रेकिंग परिवर्तन नहीं।
|
||||
|
||||
### 8. निगरानी और अवलोकन
|
||||
|
||||
#### 8.1 नए मेट्रिक्स
|
||||
|
||||
**टूल समूह उपयोग:**
|
||||
`agent_tool_group_requests_total` - समूह द्वारा अनुरोधों की संख्या।
|
||||
`agent_tool_group_availability` - प्रति समूह उपलब्ध टूल का गेज।
|
||||
`agent_filtered_tools_count` - समूह+स्थिति फ़िल्टरिंग के बाद टूल गणना का हिस्टोग्राम।
|
||||
|
||||
**स्थिति वर्कफ़्लो मेट्रिक्स:**
|
||||
`agent_state_transitions_total` - टूल द्वारा स्थिति परिवर्तनों की संख्या।
|
||||
`agent_workflow_duration_seconds` - प्रत्येक स्थिति में बिताए गए समय का हिस्टोग्राम।
|
||||
`agent_state_availability` - प्रति स्थिति उपलब्ध टूल का गेज।
|
||||
|
||||
**सुरक्षा मेट्रिक्स:**
|
||||
`agent_group_access_denied_total` - अनधिकृत समूह एक्सेस की संख्या।
|
||||
`agent_invalid_state_transition_total` - अमान्य स्थिति परिवर्तनों की संख्या।
|
||||
`agent_privilege_escalation_attempts_total` - संदिग्ध अनुरोधों की संख्या।
|
||||
|
||||
#### 8.2 लॉगिंग सुधार
|
||||
|
||||
**अनुरोध लॉगिंग:**
|
||||
```json
|
||||
{
|
||||
"request_id": "req-123",
|
||||
"requested_groups": ["read-only", "knowledge"],
|
||||
"initial_state": "undefined",
|
||||
"state_transitions": [
|
||||
{"tool": "knowledge-query", "from": "undefined", "to": "analysis", "timestamp": "2024-01-01T10:00:01Z"}
|
||||
],
|
||||
"available_tools": ["knowledge-query", "text-completion"],
|
||||
"filtered_by_group": ["graph-update", "admin-tool"],
|
||||
"filtered_by_state": [],
|
||||
"execution_time": "1.2s"
|
||||
}
|
||||
```
|
||||
|
||||
### 9. परीक्षण रणनीति
|
||||
|
||||
#### 9.1 यूनिट परीक्षण
|
||||
|
||||
**उपकरण फ़िल्टरिंग लॉजिक:**
|
||||
परीक्षण समूह इंटरसेक्शन गणनाएँ
|
||||
परीक्षण राज्य-आधारित फ़िल्टरिंग लॉजिक
|
||||
डिफ़ॉल्ट समूह और राज्य असाइनमेंट की जाँच करें
|
||||
वाइल्डकार्ड समूह व्यवहार का परीक्षण करें
|
||||
खाली समूह हैंडलिंग को मान्य करें
|
||||
संयुक्त समूह+राज्य फ़िल्टरिंग परिदृश्यों का परीक्षण करें
|
||||
|
||||
**कॉन्फ़िगरेशन सत्यापन:**
|
||||
विभिन्न समूह और राज्य कॉन्फ़िगरेशन के साथ उपकरण लोडिंग का परीक्षण करें
|
||||
अमान्य समूह और राज्य विनिर्देशों के लिए स्कीमा सत्यापन की जाँच करें
|
||||
मौजूदा कॉन्फ़िगरेशन के साथ पिछड़े अनुकूलता का परीक्षण करें
|
||||
राज्य संक्रमण परिभाषाओं और चक्रों को मान्य करें
|
||||
|
||||
#### 9.2 एकीकरण परीक्षण
|
||||
|
||||
**एजेंट व्यवहार:**
|
||||
सत्यापित करें कि एजेंट केवल समूह+राज्य फ़िल्टर किए गए उपकरणों को ही देखते हैं
|
||||
विभिन्न समूह संयोजनों के साथ अनुरोध निष्पादन का परीक्षण करें
|
||||
एजेंट निष्पादन के दौरान राज्य संक्रमणों का परीक्षण करें
|
||||
जब कोई उपकरण उपलब्ध न हो तो त्रुटि हैंडलिंग को मान्य करें
|
||||
कई राज्यों के माध्यम से वर्कफ़्लो प्रगति का परीक्षण करें
|
||||
|
||||
**सुरक्षा परीक्षण:**
|
||||
विशेषाधिकार वृद्धि रोकथाम का परीक्षण करें
|
||||
ऑडिट ट्रेल की सटीकता को सत्यापित करें
|
||||
उपयोगकर्ता अनुमतियों के साथ गेटवे एकीकरण का परीक्षण करें
|
||||
|
||||
#### 9.3 एंड-टू-एंड परिदृश्य
|
||||
|
||||
**राज्य वर्कफ़्लो के साथ मल्टी-टेनांट उपयोग:**
|
||||
```
|
||||
Scenario: Different users with different tool access and workflow states
|
||||
Given: User A has "read-only" permissions, state "undefined"
|
||||
And: User B has "write" permissions, state "analysis"
|
||||
When: Both request knowledge operations
|
||||
Then: User A gets read-only tools available in "undefined" state
|
||||
And: User B gets write tools available in "analysis" state
|
||||
And: State transitions are tracked per user session
|
||||
And: All usage and transitions are properly audited
|
||||
```
|
||||
|
||||
**कार्यप्रवाह स्थिति प्रगति:**
|
||||
```
|
||||
Scenario: Complete workflow execution
|
||||
Given: Request with groups ["knowledge", "compute"] and state "undefined"
|
||||
When: Agent executes knowledge-query tool (transitions to "analysis")
|
||||
And: Agent executes complex-analysis tool (transitions to "results")
|
||||
And: Agent executes reset-workflow tool (transitions to "undefined")
|
||||
Then: Each step has correctly filtered available tools
|
||||
And: State transitions are logged with timestamps
|
||||
And: Final state allows initial workflow to repeat
|
||||
```
|
||||
|
||||
### 10. प्रदर्शन संबंधी विचार
|
||||
|
||||
#### 10.1 टूल लोडिंग का प्रभाव
|
||||
|
||||
**कॉन्फ़िगरेशन लोडिंग:**
|
||||
समूह और स्थिति मेटाडेटा स्टार्टअप पर एक बार लोड होता है
|
||||
प्रति टूल न्यूनतम मेमोरी ओवरहेड (अतिरिक्त फ़ील्ड)
|
||||
टूल इनिशियलाइज़ेशन समय पर कोई प्रभाव नहीं
|
||||
|
||||
**अनुरोध प्रसंस्करण:**
|
||||
समूह+स्थिति फ़िल्टरिंग एक बार प्रति अनुरोध होती है
|
||||
O(n) जटिलता, जहाँ n = कॉन्फ़िगर किए गए टूल की संख्या
|
||||
राज्य परिवर्तन न्यूनतम ओवरहेड जोड़ते हैं (स्ट्रिंग असाइनमेंट)
|
||||
विशिष्ट टूल गणना के लिए नगण्य प्रभाव (< 100)
|
||||
|
||||
#### 10.2 अनुकूलन रणनीतियाँ
|
||||
|
||||
**पूर्व-गणना किए गए टूल सेट:**
|
||||
समूह+स्थिति संयोजन द्वारा टूल सेट को कैश करें
|
||||
सामान्य समूह/स्थिति पैटर्न के लिए बार-बार फ़िल्टरिंग से बचें
|
||||
बार-बार उपयोग किए जाने वाले संयोजनों के लिए मेमोरी बनाम गणना का समझौता
|
||||
|
||||
**लेज़ी लोडिंग:**
|
||||
केवल आवश्यकता पड़ने पर टूल कार्यान्वयन लोड करें
|
||||
कई टूल वाले डिप्लॉयमेंट के लिए स्टार्टअप समय कम करें
|
||||
समूह आवश्यकताओं के आधार पर गतिशील टूल पंजीकरण
|
||||
|
||||
### 11. भविष्य के सुधार
|
||||
|
||||
#### 11.1 गतिशील समूह असाइनमेंट
|
||||
|
||||
**संदर्भ-जागरूक समूहीकरण:**
|
||||
अनुरोध संदर्भ के आधार पर टूल को समूहों में असाइन करें
|
||||
समय-आधारित समूह उपलब्धता (केवल व्यावसायिक घंटों के दौरान)
|
||||
लोड-आधारित समूह प्रतिबंध (कम उपयोग के दौरान महंगे टूल)
|
||||
|
||||
#### 11.2 समूह पदानुक्रम
|
||||
|
||||
**नेस्टेड समूह संरचना:**
|
||||
```json
|
||||
{
|
||||
"knowledge": {
|
||||
"read": ["knowledge-query", "entity-search"],
|
||||
"write": ["graph-update", "entity-create"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 11.3 उपकरण अनुशंसाएँ
|
||||
|
||||
**समूह-आधारित सुझाव:**
|
||||
अनुरोध प्रकारों के लिए इष्टतम उपकरण समूहों का सुझाव दें
|
||||
अनुशंसाओं को बेहतर बनाने के लिए उपयोग पैटर्न से सीखें
|
||||
जब पसंदीदा उपकरण उपलब्ध न हों तो वैकल्पिक समूहों का प्रावधान करें
|
||||
|
||||
### 12. खुले प्रश्न
|
||||
|
||||
1. **समूह सत्यापन**: क्या अनुरोधों में अमान्य समूह नामों के कारण हार्ड विफलताएँ या चेतावनियाँ आनी चाहिए?
|
||||
|
||||
2. **समूह खोज**: क्या सिस्टम उपलब्ध समूहों और उनके उपकरणों की सूची प्रदान करने के लिए एक एपीआई प्रदान करना चाहिए?
|
||||
|
||||
3. **गतिशील समूह**: क्या समूहों को रनटाइम पर या केवल स्टार्टअप पर ही कॉन्फ़िगर किया जाना चाहिए?
|
||||
|
||||
4. **समूह विरासत**: क्या उपकरणों को अपने मूल श्रेणियों या कार्यान्वयन से समूहों को विरासत में मिलना चाहिए?
|
||||
|
||||
5. **प्रदर्शन निगरानी**: समूह-आधारित उपकरण उपयोग को प्रभावी ढंग से ट्रैक करने के लिए किन अतिरिक्त मेट्रिक्स की आवश्यकता है?
|
||||
|
||||
### 13. निष्कर्ष
|
||||
|
||||
उपकरण समूह प्रणाली निम्नलिखित प्रदान करती है:
|
||||
|
||||
**सुरक्षा**: एजेंट क्षमताओं पर बारीक पहुंच नियंत्रण
|
||||
**प्रदर्शन**: उपकरण लोडिंग और चयन ओवरहेड में कमी
|
||||
**लचीलापन**: बहु-आयामी उपकरण वर्गीकरण
|
||||
**संगतता**: मौजूदा एजेंट आर्किटेक्चर के साथ निर्बाध एकीकरण
|
||||
|
||||
यह प्रणाली ट्रस्टग्राफ परिनियोजन को उपकरण पहुंच को बेहतर ढंग से प्रबंधित करने, सुरक्षा सीमाओं में सुधार करने और मौजूदा कॉन्फ़िगरेशन और अनुरोधों के साथ पूर्ण पिछड़े संगतता बनाए रखते हुए संसाधन उपयोग को अनुकूलित करने में सक्षम बनाती है।
|
||||
479
docs/tech-specs/hi/tool-services.hi.md
Normal file
479
docs/tech-specs/hi/tool-services.hi.md
Normal file
|
|
@ -0,0 +1,479 @@
|
|||
---
|
||||
layout: default
|
||||
title: "टूल सेवाएं: गतिशील रूप से प्लगेबल एजेंट टूल"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# टूल सेवाएं: गतिशील रूप से प्लगेबल एजेंट टूल
|
||||
|
||||
> **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.
|
||||
|
||||
## स्थिति
|
||||
|
||||
कार्यान्वित
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह विनिर्देश "टूल सेवाओं" नामक गतिशील रूप से प्लगेबल एजेंट टूल के लिए एक तंत्र को परिभाषित करता है। मौजूदा अंतर्निहित टूल प्रकारों (`KnowledgeQueryImpl`, `McpToolImpl`, आदि) के विपरीत, टूल सेवाएं नए टूल को इस प्रकार पेश करने की अनुमति देती हैं:
|
||||
|
||||
1. एक नई पल्सर-आधारित सेवा को तैनात करना
|
||||
2. एक कॉन्फ़िगरेशन विवरण जोड़ना जो एजेंट को बताता है कि इसे कैसे कॉल करना है
|
||||
|
||||
यह मुख्य एजेंट-रिएक्ट फ्रेमवर्क को संशोधित किए बिना विस्तारशीलता को सक्षम बनाता है।
|
||||
|
||||
## शब्दावली
|
||||
|
||||
| शब्द | परिभाषा |
|
||||
|------|------------|
|
||||
| **अंतर्निहित टूल** | `tools.py` में हार्डकोडेड कार्यान्वयन वाले मौजूदा टूल प्रकार
|
||||
| **टूल सेवा** | एक पल्सर सेवा जिसे एजेंट टूल के रूप में कॉल किया जा सकता है, जिसे एक सेवा विवरण द्वारा परिभाषित किया गया है
|
||||
| **टूल** | एक कॉन्फ़िगर किया गया उदाहरण जो एक टूल सेवा को संदर्भित करता है, जो एजेंट/एलएलएम को उजागर किया जाता है
|
||||
|
||||
यह एक दो-स्तरीय मॉडल है, जो एमसीपी टूल के समान है:
|
||||
एमसीपी: एमसीपी सर्वर टूल इंटरफ़ेस को परिभाषित करता है → टूल कॉन्फ़िगरेशन इसका संदर्भ देता है
|
||||
टूल सेवाएं: टूल सेवा पल्सर इंटरफ़ेस को परिभाषित करती है → टूल कॉन्फ़िगरेशन इसका संदर्भ देता है
|
||||
|
||||
## पृष्ठभूमि: मौजूदा टूल
|
||||
|
||||
### अंतर्निहित टूल कार्यान्वयन
|
||||
|
||||
टूल वर्तमान में `trustgraph-flow/trustgraph/agent/react/tools.py` में टाइप किए गए कार्यान्वयन के साथ परिभाषित किए गए हैं:
|
||||
|
||||
```python
|
||||
class KnowledgeQueryImpl:
|
||||
async def invoke(self, question):
|
||||
client = self.context("graph-rag-request")
|
||||
return await client.rag(question, self.collection)
|
||||
```
|
||||
|
||||
प्रत्येक उपकरण प्रकार:
|
||||
में एक हार्डकोडेड पल्सर सेवा होती है जिसे वह कॉल करता है (उदाहरण के लिए, `graph-rag-request`)
|
||||
वह क्लाइंट पर कॉल करने के लिए सटीक विधि जानता है (उदाहरण के लिए, `client.rag()`)
|
||||
इसमें कार्यान्वयन में परिभाषित टाइप किए गए तर्क होते हैं
|
||||
|
||||
### उपकरण पंजीकरण (service.py:105-214)
|
||||
|
||||
उपकरण कॉन्फ़िगरेशन से लोड किए जाते हैं जिसमें एक `type` फ़ील्ड होता है जो एक कार्यान्वयन से मेल खाता है:
|
||||
|
||||
```python
|
||||
if impl_id == "knowledge-query":
|
||||
impl = functools.partial(KnowledgeQueryImpl, collection=data.get("collection"))
|
||||
elif impl_id == "text-completion":
|
||||
impl = TextCompletionImpl
|
||||
# ... etc
|
||||
```
|
||||
|
||||
## आर्किटेक्चर
|
||||
|
||||
### दो-स्तरीय मॉडल
|
||||
|
||||
#### स्तर 1: टूल सर्विस डिस्क्रिप्टर
|
||||
|
||||
एक टूल सर्विस, पल्सर सर्विस इंटरफेस को परिभाषित करता है। यह निम्नलिखित घोषित करता है:
|
||||
अनुरोध/प्रतिक्रिया के लिए पल्सर क्यू
|
||||
उन कॉन्फ़िगरेशन पैरामीटर जिन्हें इसका उपयोग करने वाले टूल से इसकी आवश्यकता होती है
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "custom-rag",
|
||||
"request-queue": "non-persistent://tg/request/custom-rag",
|
||||
"response-queue": "non-persistent://tg/response/custom-rag",
|
||||
"config-params": [
|
||||
{"name": "collection", "required": true}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
एक उपकरण सेवा जिसे किसी भी कॉन्फ़िगरेशन पैरामीटर की आवश्यकता नहीं है:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "calculator",
|
||||
"request-queue": "non-persistent://tg/request/calc",
|
||||
"response-queue": "non-persistent://tg/response/calc",
|
||||
"config-params": []
|
||||
}
|
||||
```
|
||||
|
||||
#### स्तर 2: टूल विवरणिका
|
||||
|
||||
एक टूल एक टूल सेवा को संदर्भित करता है और निम्नलिखित प्रदान करता है:
|
||||
कॉन्फ़िगरेशन पैरामीटर मान (सेवा की आवश्यकताओं को पूरा करते हुए)
|
||||
एजेंट के लिए टूल मेटाडेटा (नाम, विवरण)
|
||||
एलएलएम के लिए तर्क परिभाषाएँ
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "tool-service",
|
||||
"name": "query-customers",
|
||||
"description": "Query the customer knowledge base",
|
||||
"service": "custom-rag",
|
||||
"collection": "customers",
|
||||
"arguments": [
|
||||
{
|
||||
"name": "question",
|
||||
"type": "string",
|
||||
"description": "The question to ask about customers"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
कई उपकरण एक ही सेवा को विभिन्न कॉन्फ़िगरेशन के साथ संदर्भित कर सकते हैं:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "tool-service",
|
||||
"name": "query-products",
|
||||
"description": "Query the product knowledge base",
|
||||
"service": "custom-rag",
|
||||
"collection": "products",
|
||||
"arguments": [
|
||||
{
|
||||
"name": "question",
|
||||
"type": "string",
|
||||
"description": "The question to ask about products"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### अनुरोध प्रारूप
|
||||
|
||||
जब कोई टूल सक्रिय किया जाता है, तो टूल सेवा को भेजा गया अनुरोध में शामिल होता है:
|
||||
`user`: एजेंट अनुरोध से (मल्टी-टेनेंसी)
|
||||
`config`: टूल विवरणिका से JSON-एन्कोडेड कॉन्फ़िगरेशन मान
|
||||
`arguments`: LLM से JSON-एन्कोडेड तर्क
|
||||
|
||||
```json
|
||||
{
|
||||
"user": "alice",
|
||||
"config": "{\"collection\": \"customers\"}",
|
||||
"arguments": "{\"question\": \"What are the top customer complaints?\"}"
|
||||
}
|
||||
```
|
||||
|
||||
टूल सर्विस इन डेटा को पार्स किए गए डिक्शनरी के रूप में `invoke` मेथड में प्राप्त करती है।
|
||||
|
||||
### सामान्य टूल सर्विस कार्यान्वयन
|
||||
|
||||
एक `ToolServiceImpl` क्लास कॉन्फ़िगरेशन के आधार पर टूल सेवाओं को लागू करता है:
|
||||
|
||||
```python
|
||||
class ToolServiceImpl:
|
||||
def __init__(self, context, request_queue, response_queue, config_values, arguments, processor):
|
||||
self.request_queue = request_queue
|
||||
self.response_queue = response_queue
|
||||
self.config_values = config_values # e.g., {"collection": "customers"}
|
||||
# ...
|
||||
|
||||
async def invoke(self, **arguments):
|
||||
client = await self._get_or_create_client()
|
||||
response = await client.call(user, self.config_values, arguments)
|
||||
if isinstance(response, str):
|
||||
return response
|
||||
else:
|
||||
return json.dumps(response)
|
||||
```
|
||||
|
||||
## डिज़ाइन निर्णय
|
||||
|
||||
### दो-स्तरीय कॉन्फ़िगरेशन मॉडल
|
||||
|
||||
टूल सेवाएं एमसीपी टूल के समान एक दो-स्तरीय मॉडल का पालन करती हैं:
|
||||
|
||||
1. **टूल सेवा**: पल्सर सेवा इंटरफ़ेस को परिभाषित करती है (विषय, आवश्यक कॉन्फ़िगरेशन पैरामीटर)
|
||||
2. **टूल**: एक टूल सेवा को संदर्भित करता है, कॉन्फ़िगरेशन मान प्रदान करता है, एलएलएम तर्क को परिभाषित करता है
|
||||
|
||||
यह अलगाव अनुमति देता है:
|
||||
एक टूल सेवा का उपयोग विभिन्न कॉन्फ़िगरेशन वाले कई टूल द्वारा किया जा सकता है
|
||||
सेवा इंटरफ़ेस और टूल कॉन्फ़िगरेशन के बीच स्पष्ट अंतर
|
||||
सेवा परिभाषाओं का पुन: उपयोग
|
||||
|
||||
### अनुरोध मैपिंग: एन्वेलप के साथ पास-थ्रू
|
||||
|
||||
एक टूल सेवा के लिए अनुरोध एक संरचित एन्वेलप होता है जिसमें शामिल हैं:
|
||||
`user`: मल्टी-टेनेंसी के लिए एजेंट अनुरोध से प्रचारित
|
||||
कॉन्फ़िगरेशन मान: टूल विवरणिका से (उदाहरण के लिए, `collection`)
|
||||
`arguments`: एलएलएम-प्रदत्त तर्क, एक डिक्ट के रूप में पास किए जाते हैं
|
||||
|
||||
एजेंट प्रबंधक एलएलएम की प्रतिक्रिया को `act.arguments` के रूप में एक डिक्ट (`agent_manager.py:117-154`) में पार्स करता है। यह डिक्ट अनुरोध एन्वेलप में शामिल है।
|
||||
|
||||
### स्कीमा हैंडलिंग: अनटाइप्ड
|
||||
|
||||
अनुरोध और प्रतिक्रियाएं अनटाइप्ड डिक्ट का उपयोग करती हैं। एजेंट स्तर पर कोई स्कीमा सत्यापन नहीं होता है - टूल सेवा अपने इनपुट को मान्य करने के लिए जिम्मेदार है। यह नई सेवाओं को परिभाषित करने के लिए अधिकतम लचीलापन प्रदान करता है।
|
||||
|
||||
### क्लाइंट इंटरफ़ेस: डायरेक्ट पल्सर टॉपिक
|
||||
|
||||
टूल सेवाएं प्रवाह कॉन्फ़िगरेशन की आवश्यकता के बिना डायरेक्ट पल्सर टॉपिक का उपयोग करती हैं। टूल-सेवा विवरणिका पूर्ण कतार नामों को निर्दिष्ट करती है:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "joke-service",
|
||||
"request-queue": "non-persistent://tg/request/joke",
|
||||
"response-queue": "non-persistent://tg/response/joke",
|
||||
"config-params": [...]
|
||||
}
|
||||
```
|
||||
|
||||
यह सेवाओं को किसी भी नेमस्पेस में होस्ट करने की अनुमति देता है।
|
||||
|
||||
### त्रुटि प्रबंधन: मानक त्रुटि सम्मेलन
|
||||
|
||||
टूल सेवा प्रतिक्रियाएं मौजूदा स्कीमा सम्मेलन का पालन करती हैं, जिसमें एक `error` फ़ील्ड है:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class Error:
|
||||
type: str = ""
|
||||
message: str = ""
|
||||
```
|
||||
|
||||
प्रतिक्रिया संरचना:
|
||||
सफलता: `error` का मान `None` है, प्रतिक्रिया में परिणाम शामिल है
|
||||
त्रुटि: `error` को `type` और `message` के मानों के साथ भरा जाता है
|
||||
|
||||
यह मौजूदा सेवा स्कीमा में उपयोग किए गए पैटर्न से मेल खाता है (उदाहरण के लिए, `PromptResponse`, `QueryResponse`, `AgentResponse`)।
|
||||
|
||||
### अनुरोध/प्रतिक्रिया सहसंबंध
|
||||
|
||||
अनुरोधों और प्रतिक्रियाओं को पल्सर संदेश गुणों में एक `id` का उपयोग करके सहसंबंधित किया जाता है:
|
||||
|
||||
अनुरोध में गुणों में `id` शामिल है: `properties={"id": id}`
|
||||
प्रतिक्रिया(ओं) में समान `id` शामिल है: `properties={"id": id}`
|
||||
|
||||
यह पूरे कोडबेस में उपयोग किए गए मौजूदा पैटर्न का अनुसरण करता है (उदाहरण के लिए, `agent_service.py`, `llm_service.py`)।
|
||||
|
||||
### स्ट्रीमिंग समर्थन
|
||||
|
||||
टूल सेवाएं स्ट्रीमिंग प्रतिक्रियाएं वापस कर सकती हैं:
|
||||
|
||||
समान `id` वाले कई प्रतिक्रिया संदेश
|
||||
प्रत्येक प्रतिक्रिया में `end_of_stream: bool` फ़ील्ड शामिल है
|
||||
अंतिम प्रतिक्रिया में `end_of_stream: True` है
|
||||
|
||||
यह `AgentResponse` और अन्य स्ट्रीमिंग सेवाओं में उपयोग किए गए पैटर्न से मेल खाता है।
|
||||
|
||||
### प्रतिक्रिया हैंडलिंग: स्ट्रिंग रिटर्न
|
||||
|
||||
सभी मौजूदा टूल समान पैटर्न का पालन करते हैं: **तर्कों को एक डिक्ट के रूप में प्राप्त करें, अवलोकन को एक स्ट्रिंग के रूप में वापस करें।**
|
||||
|
||||
| टूल | प्रतिक्रिया हैंडलिंग |
|
||||
|------|------------------|
|
||||
| `KnowledgeQueryImpl` | `client.rag()` को सीधे वापस करता है (स्ट्रिंग) |
|
||||
| `TextCompletionImpl` | `client.question()` को सीधे वापस करता है (स्ट्रिंग) |
|
||||
| `McpToolImpl` | एक स्ट्रिंग वापस करता है, या यदि स्ट्रिंग नहीं है तो `json.dumps(output)` |
|
||||
| `StructuredQueryImpl` | परिणाम को स्ट्रिंग में प्रारूपित करता है |
|
||||
| `PromptImpl` | `client.prompt()` को सीधे वापस करता है (स्ट्रिंग) |
|
||||
|
||||
टूल सेवाएं समान अनुबंध का पालन करती हैं:
|
||||
सेवा एक स्ट्रिंग प्रतिक्रिया (अवलोकन) वापस करती है
|
||||
यदि प्रतिक्रिया एक स्ट्रिंग नहीं है, तो इसे `json.dumps()` के माध्यम से परिवर्तित किया जाता है
|
||||
वर्णनकर्ता में किसी निष्कर्षण कॉन्फ़िगरेशन की आवश्यकता नहीं है
|
||||
|
||||
यह वर्णनकर्ता को सरल रखता है और सेवा पर एजेंट के लिए एक उपयुक्त पाठ प्रतिक्रिया वापस करने की जिम्मेदारी डालता है।
|
||||
|
||||
## कॉन्फ़िगरेशन गाइड
|
||||
|
||||
एक नई टूल सेवा जोड़ने के लिए, दो कॉन्फ़िगरेशन आइटम की आवश्यकता होती है:
|
||||
|
||||
### 1. टूल सेवा कॉन्फ़िगरेशन
|
||||
|
||||
`tool-service` कॉन्फ़िगरेशन कुंजी के अंतर्गत संग्रहीत। पल्सर कतारों और उपलब्ध कॉन्फ़िगरेशन मापदंडों को परिभाषित करता है।
|
||||
|
||||
| फ़ील्ड | आवश्यक | विवरण |
|
||||
|-------|----------|-------------|
|
||||
| `id` | हाँ | टूल सेवा के लिए अद्वितीय पहचानकर्ता |
|
||||
| `request-queue` | हाँ | अनुरोधों के लिए पूर्ण पल्सर विषय (उदाहरण के लिए, `non-persistent://tg/request/joke`) |
|
||||
| `response-queue` | हाँ | प्रतिक्रियाओं के लिए पूर्ण पल्सर विषय (उदाहरण के लिए, `non-persistent://tg/response/joke`) |
|
||||
| `config-params` | नहीं | सेवा द्वारा स्वीकार किए जाने वाले कॉन्फ़िगरेशन मापदंडों की सरणी |
|
||||
|
||||
प्रत्येक कॉन्फ़िगरेशन पैरामीटर में निम्नलिखित निर्दिष्ट किया जा सकता है:
|
||||
`name`: पैरामीटर नाम (आवश्यक)
|
||||
`required`: क्या पैरामीटर को टूल द्वारा प्रदान किया जाना चाहिए (डिफ़ॉल्ट: झूठा)
|
||||
|
||||
उदाहरण:
|
||||
```json
|
||||
{
|
||||
"id": "joke-service",
|
||||
"request-queue": "non-persistent://tg/request/joke",
|
||||
"response-queue": "non-persistent://tg/response/joke",
|
||||
"config-params": [
|
||||
{"name": "style", "required": false}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. टूल कॉन्फ़िगरेशन
|
||||
|
||||
`tool` कुंजी के अंतर्गत संग्रहीत। यह एक ऐसा टूल परिभाषित करता है जिसका उपयोग एजेंट कर सकता है।
|
||||
|
||||
| फ़ील्ड | आवश्यक | विवरण |
|
||||
|-------|----------|-------------|
|
||||
| `type` | हाँ | यह `"tool-service"` होना चाहिए |
|
||||
| `name` | हाँ | एलएलएम को प्रदर्शित होने वाला टूल नाम |
|
||||
| `description` | हाँ | टूल क्या करता है इसका विवरण (एलएलएम को दिखाया जाता है) |
|
||||
| `service` | हाँ | टूल-सर्विस का आईडी जिसे कॉल किया जाना है |
|
||||
| `arguments` | नहीं | एलएलएम के लिए तर्क परिभाषाओं का सरणी |
|
||||
| *(कॉन्फ़िगरेशन पैरामीटर)* | भिन्न | सेवा द्वारा परिभाषित कोई भी कॉन्फ़िगरेशन पैरामीटर |
|
||||
|
||||
प्रत्येक तर्क में निम्नलिखित निर्दिष्ट किया जा सकता है:
|
||||
`name`: तर्क का नाम (आवश्यक)
|
||||
`type`: डेटा प्रकार, उदाहरण के लिए, `"string"` (आवश्यक)
|
||||
`description`: एलएलएम को दिखाया जाने वाला विवरण (आवश्यक)
|
||||
|
||||
उदाहरण:
|
||||
```json
|
||||
{
|
||||
"type": "tool-service",
|
||||
"name": "tell-joke",
|
||||
"description": "Tell a joke on a given topic",
|
||||
"service": "joke-service",
|
||||
"style": "pun",
|
||||
"arguments": [
|
||||
{
|
||||
"name": "topic",
|
||||
"type": "string",
|
||||
"description": "The topic for the joke (e.g., programming, animals, food)"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### कॉन्फ़िगरेशन लोड करना
|
||||
|
||||
कॉन्फ़िगरेशन लोड करने के लिए `tg-put-config-item` का उपयोग करें:
|
||||
|
||||
```bash
|
||||
# Load tool-service config
|
||||
tg-put-config-item tool-service/joke-service < joke-service.json
|
||||
|
||||
# Load tool config
|
||||
tg-put-config-item tool/tell-joke < tell-joke.json
|
||||
```
|
||||
|
||||
एजेंट-मैनेजर को नए कॉन्फ़िगरेशन को लागू करने के लिए पुनरारंभ किया जाना चाहिए।
|
||||
|
||||
## कार्यान्वयन विवरण
|
||||
|
||||
### स्कीमा
|
||||
|
||||
`trustgraph-base/trustgraph/schema/services/tool_service.py` में अनुरोध और प्रतिक्रिया प्रकार:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class ToolServiceRequest:
|
||||
user: str = "" # User context for multi-tenancy
|
||||
config: str = "" # JSON-encoded config values from tool descriptor
|
||||
arguments: str = "" # JSON-encoded arguments from LLM
|
||||
|
||||
@dataclass
|
||||
class ToolServiceResponse:
|
||||
error: Error | None = None
|
||||
response: str = "" # String response (the observation)
|
||||
end_of_stream: bool = False
|
||||
```
|
||||
|
||||
### सर्वर-साइड: डायनामिकटूलसर्विस
|
||||
|
||||
`trustgraph-base/trustgraph/base/dynamic_tool_service.py` में बेस क्लास:
|
||||
|
||||
```python
|
||||
class DynamicToolService(AsyncProcessor):
|
||||
"""Base class for implementing tool services."""
|
||||
|
||||
def __init__(self, **params):
|
||||
topic = params.get("topic", default_topic)
|
||||
# Constructs topics: non-persistent://tg/request/{topic}, non-persistent://tg/response/{topic}
|
||||
# Sets up Consumer and Producer
|
||||
|
||||
async def invoke(self, user, config, arguments):
|
||||
"""Override this method to implement the tool's logic."""
|
||||
raise NotImplementedError()
|
||||
```
|
||||
|
||||
### क्लाइंट-साइड: ToolServiceImpl
|
||||
|
||||
`trustgraph-flow/trustgraph/agent/react/tools.py` में कार्यान्वयन:
|
||||
|
||||
```python
|
||||
class ToolServiceImpl:
|
||||
def __init__(self, context, request_queue, response_queue, config_values, arguments, processor):
|
||||
# Uses the provided queue paths directly
|
||||
# Creates ToolServiceClient on first use
|
||||
|
||||
async def invoke(self, **arguments):
|
||||
client = await self._get_or_create_client()
|
||||
response = await client.call(user, config_values, arguments)
|
||||
return response if isinstance(response, str) else json.dumps(response)
|
||||
```
|
||||
|
||||
### फ़ाइलें
|
||||
|
||||
| फ़ाइल | उद्देश्य |
|
||||
|------|---------|
|
||||
| `trustgraph-base/trustgraph/schema/services/tool_service.py` | अनुरोध/प्रतिक्रिया स्कीमा |
|
||||
| `trustgraph-base/trustgraph/base/tool_service_client.py` | सेवाओं को आमंत्रित करने के लिए क्लाइंट |
|
||||
| `trustgraph-base/trustgraph/base/dynamic_tool_service.py` | सेवा कार्यान्वयन के लिए आधार वर्ग |
|
||||
| `trustgraph-flow/trustgraph/agent/react/tools.py` | `ToolServiceImpl` वर्ग |
|
||||
| `trustgraph-flow/trustgraph/agent/react/service.py` | कॉन्फ़िगरेशन लोडिंग |
|
||||
|
||||
### उदाहरण: जोक सर्विस
|
||||
|
||||
`trustgraph-flow/trustgraph/tool_service/joke/` में एक उदाहरण सेवा:
|
||||
|
||||
```python
|
||||
class Processor(DynamicToolService):
|
||||
async def invoke(self, user, config, arguments):
|
||||
style = config.get("style", "pun")
|
||||
topic = arguments.get("topic", "")
|
||||
joke = pick_joke(topic, style)
|
||||
return f"Hey {user}! Here's a {style} for you:\n\n{joke}"
|
||||
```
|
||||
|
||||
टूल सर्विस कॉन्फ़िगरेशन:
|
||||
```json
|
||||
{
|
||||
"id": "joke-service",
|
||||
"request-queue": "non-persistent://tg/request/joke",
|
||||
"response-queue": "non-persistent://tg/response/joke",
|
||||
"config-params": [{"name": "style", "required": false}]
|
||||
}
|
||||
```
|
||||
|
||||
टूल कॉन्फ़िगरेशन:
|
||||
```json
|
||||
{
|
||||
"type": "tool-service",
|
||||
"name": "tell-joke",
|
||||
"description": "Tell a joke on a given topic",
|
||||
"service": "joke-service",
|
||||
"style": "pun",
|
||||
"arguments": [
|
||||
{"name": "topic", "type": "string", "description": "The topic for the joke"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### पिछली अनुकूलता (पिछड़ी संगतता)
|
||||
|
||||
मौजूदा अंतर्निहित टूल प्रकार बिना किसी बदलाव के काम करना जारी रखते हैं।
|
||||
`tool-service` एक नया टूल प्रकार है जो मौजूदा प्रकारों (`knowledge-query`, `mcp-tool`, आदि) के साथ है।
|
||||
|
||||
## भविष्य के विचार
|
||||
|
||||
### स्व-घोषणा करने वाली सेवाएं
|
||||
|
||||
एक भविष्य का सुधार सेवाओं को अपने स्वयं के विवरण प्रकाशित करने की अनुमति दे सकता है:
|
||||
|
||||
सेवाएं स्टार्टअप पर एक ज्ञात `tool-descriptors` विषय पर प्रकाशित करती हैं।
|
||||
एजेंट सदस्यता लेता है और गतिशील रूप से टूल पंजीकृत करता है।
|
||||
यह वास्तविक प्लग-एंड-प्ले को कॉन्फ़िगरेशन परिवर्तनों के बिना सक्षम बनाता है।
|
||||
|
||||
यह प्रारंभिक कार्यान्वयन के दायरे से बाहर है।
|
||||
|
||||
## संदर्भ
|
||||
|
||||
वर्तमान टूल कार्यान्वयन: `trustgraph-flow/trustgraph/agent/react/tools.py`
|
||||
टूल पंजीकरण: `trustgraph-flow/trustgraph/agent/react/service.py:105-214`
|
||||
एजेंट स्कीमा: `trustgraph-base/trustgraph/schema/services/agent.py`
|
||||
404
docs/tech-specs/hi/universal-decoder.hi.md
Normal file
404
docs/tech-specs/hi/universal-decoder.hi.md
Normal file
|
|
@ -0,0 +1,404 @@
|
|||
---
|
||||
layout: default
|
||||
title: "यूनिवर्सल डॉक्यूमेंट डिकोडर"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# यूनिवर्सल डॉक्यूमेंट डिकोडर
|
||||
|
||||
> **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.
|
||||
|
||||
## शीर्षक
|
||||
|
||||
यूनिवर्सल डॉक्यूमेंट डिकोडर जो `unstructured` द्वारा संचालित है — किसी भी सामान्य
|
||||
डॉक्यूमेंट फॉर्मेट को एक ही सेवा के माध्यम से संसाधित करें, जिसमें पूर्ण उत्पत्ति और लाइब्रेरियन
|
||||
एकीकरण शामिल है, जो स्रोत स्थितियों को ज्ञान ग्राफ मेटाडेटा के रूप में रिकॉर्ड करता है ताकि
|
||||
एंड-टू-एंड पता लगाया जा सके।
|
||||
|
||||
## समस्या
|
||||
|
||||
वर्तमान में ट्रस्टग्राफ में एक पीडीएफ-विशिष्ट डिकोडर है। अतिरिक्त
|
||||
फॉर्मेट (DOCX, XLSX, HTML, Markdown, प्लेन टेक्स्ट, PPTX, आदि) का समर्थन करने के लिए
|
||||
या तो प्रत्येक फॉर्मेट के लिए एक नया डिकोडर लिखना होगा या एक सार्वभौमिक निष्कर्षण
|
||||
लाइब्रेरी को अपनाना होगा। प्रत्येक फॉर्मेट की संरचना अलग होती है — कुछ पृष्ठ-आधारित होते हैं, कुछ
|
||||
नहीं होते हैं — और निष्कर्षित पाठ के प्रत्येक टुकड़े की उत्पत्ति मूल
|
||||
डॉक्यूमेंट में कहां से हुई, इसे उत्पत्ति श्रृंखला में रिकॉर्ड किया जाना चाहिए।
|
||||
|
||||
## दृष्टिकोण
|
||||
|
||||
### लाइब्रेरी: `unstructured`
|
||||
|
||||
`unstructured.partition.auto.partition()` का उपयोग करें जो फॉर्मेट को स्वचालित रूप से पहचानता है
|
||||
mime टाइप या फ़ाइल एक्सटेंशन से और संरचित तत्वों को निकालता है
|
||||
(शीर्षक, वर्णनात्मक पाठ, तालिका, सूची आइटम, आदि)। प्रत्येक तत्व में
|
||||
मेटाडेटा शामिल है:
|
||||
|
||||
`page_number` (पीडीएफ, पीपीटीएक्स जैसे पृष्ठ-आधारित फॉर्मेट के लिए)
|
||||
`element_id` (प्रत्येक तत्व के लिए अद्वितीय)
|
||||
`coordinates` (पीडीएफ के लिए बाउंडिंग बॉक्स)
|
||||
`text` (निष्कर्षित पाठ सामग्री)
|
||||
`category` (तत्व प्रकार: शीर्षक, वर्णनात्मक पाठ, तालिका, आदि)
|
||||
|
||||
### तत्व प्रकार
|
||||
|
||||
`unstructured` डॉक्यूमेंट से टाइप किए गए तत्वों को निकालता है। प्रत्येक तत्व में
|
||||
एक श्रेणी और संबंधित मेटाडेटा होता है:
|
||||
|
||||
**पाठ तत्व:**
|
||||
`Title` — अनुभाग शीर्षक
|
||||
`NarrativeText` — पैराग्राफ
|
||||
`ListItem` — बुलेट/क्रमांकित सूची आइटम
|
||||
`Header`, `Footer` — पृष्ठ हेडर/फुटर
|
||||
`FigureCaption` — चित्रों/छवियों के लिए कैप्शन
|
||||
`Formula` — गणितीय व्यंजक
|
||||
`Address`, `EmailAddress` — संपर्क जानकारी
|
||||
`CodeSnippet` — कोड ब्लॉक (मार्कडाउन से)
|
||||
|
||||
**तालिकाएँ:**
|
||||
`Table` — संरचित सारणीबद्ध डेटा। `unstructured` दोनों प्रदान करता है
|
||||
`element.text` (सादा पाठ) और `element.metadata.text_as_html`
|
||||
(पंक्तियों, स्तंभों और शीर्षकों को संरक्षित करते हुए पूर्ण HTML `<table>`)।
|
||||
DOCX, XLSX, HTML जैसे स्पष्ट तालिका संरचना वाले फॉर्मेट के लिए,
|
||||
निष्कर्षण अत्यधिक विश्वसनीय है। पीडीएफ के लिए, तालिका का पता लगाना
|
||||
लेआउट विश्लेषण के साथ `hi_res` रणनीति पर निर्भर करता है।
|
||||
|
||||
**छवियाँ:**
|
||||
`Image` — लेआउट विश्लेषण के माध्यम से पता लगाई गई एम्बेडेड छवियां (आवश्यक
|
||||
`hi_res` रणनीति)। `extract_image_block_to_payload=True` के साथ,
|
||||
छवि डेटा को `element.metadata.image_base64` में base64 के रूप में लौटाता है।
|
||||
छवि से OCR पाठ `element.text` में उपलब्ध है।
|
||||
|
||||
### तालिका हैंडलिंग
|
||||
|
||||
तालिकाओं को एक प्राथमिक आउटपुट माना जाता है। जब डिकोडर एक `Table`
|
||||
तत्व का सामना करता है, तो यह सादे पाठ में समतल करने के बजाय HTML संरचना को संरक्षित करता है।
|
||||
यह डाउनस्ट्रीम एलएलएम निष्कर्षण को सारणीबद्ध डेटा से संरचित ज्ञान निकालने के लिए
|
||||
बहुत बेहतर इनपुट देता है।
|
||||
|
||||
पृष्ठ/अनुभाग पाठ को इस प्रकार जोड़ा जाता है:
|
||||
पाठ तत्व: सादा पाठ, नई पंक्तियों के साथ जोड़ा गया
|
||||
तालिका तत्व: `text_as_html` से HTML तालिका मार्कअप, एक
|
||||
`<table>` मार्कर में लपेटा गया ताकि एलएलएम तालिकाओं को वर्णनात्मक
|
||||
पाठ से अलग कर सके।
|
||||
उदाहरण के लिए, एक शीर्षक, पैराग्राफ और तालिका वाला पृष्ठ इस प्रकार होगा:
|
||||
|
||||
```
|
||||
Financial Overview
|
||||
|
||||
Revenue grew 15% year-over-year driven by enterprise adoption.
|
||||
|
||||
<table>
|
||||
<tr><th>Quarter</th><th>Revenue</th><th>Growth</th></tr>
|
||||
<tr><td>Q1</td><td>$12M</td><td>12%</td></tr>
|
||||
<tr><td>Q2</td><td>$14M</td><td>17%</td></tr>
|
||||
</table>
|
||||
```
|
||||
|
||||
यह चंकिंग के माध्यम से तालिका संरचना को संरक्षित करता है और निष्कर्षण
|
||||
पाइपलाइन में, जहां एलएलएम सीधे संरचित कोशिकाओं से संबंधों को निकाल सकता है,
|
||||
कॉलम संरेखण का अनुमान लगाने के बजाय खाली स्थान से।
|
||||
|
||||
|
||||
### छवि प्रबंधन
|
||||
|
||||
छवियों को लाइब्रेरियन में चाइल्ड दस्तावेज़ों के रूप में निकाला और संग्रहीत किया जाता है
|
||||
`document_type="image"` और एक `urn:image:{uuid}` आईडी के साथ। उन्हें
|
||||
प्रकार `tg:Image` के साथ प्रामाणिकता ट्रिपल मिलते हैं, जो उनके मूल
|
||||
पृष्ठ/अनुभाग से `prov:wasDerivedFrom` के माध्यम से जुड़े होते हैं। छवि मेटाडेटा (निर्देशांक,
|
||||
आयाम, तत्व_आईडी) को प्रामाणिकता में दर्ज किया जाता है।
|
||||
|
||||
**महत्वपूर्ण रूप से, छवियों को टेक्स्टडॉक्यूमेंट आउटपुट के रूप में उत्सर्जित नहीं किया जाता है।** वे
|
||||
केवल संग्रहीत होते हैं - चंकर या किसी भी टेक्स्ट प्रोसेसिंग
|
||||
पाइपलाइन में नीचे की ओर नहीं भेजे जाते हैं। यह जानबूझकर है:
|
||||
|
||||
1. अभी तक कोई छवि प्रसंस्करण पाइपलाइन नहीं है (विज़न मॉडल एकीकरण
|
||||
भविष्य का कार्य है)
|
||||
2. आधार64 छवि डेटा या ओसीआर टुकड़ों को टेक्स्ट निष्कर्षण
|
||||
पाइपलाइन में फीड करने से कचरा केजी ट्रिपल उत्पन्न होंगे
|
||||
|
||||
छवियों को असेंबल किए गए पृष्ठ टेक्स्ट से भी बाहर रखा गया है - कोई भी `Image`
|
||||
तत्व एक पृष्ठ/अनुभाग के लिए तत्व टेक्स्ट को संयोजित करते समय चुपचाप छोड़ दिए जाते हैं। प्रामाणिकता श्रृंखला में दर्ज किया गया है कि छवियां मौजूद हैं और वे दस्तावेज़ में कहां दिखाई दीं, ताकि उन्हें भविष्य के
|
||||
पृष्ठ/अनुभाग। उत्पत्ति श्रृंखला में दर्ज है कि चित्र मौजूद हैं और वे कहाँ स्थित हैं।
|
||||
छवि प्रसंस्करण पाइपलाइन द्वारा दस्तावेज़ को फिर से संसाधित किए बिना प्राप्त किया जा सके।
|
||||
|
||||
|
||||
#### भविष्य का कार्य
|
||||
|
||||
`tg:Image` संस्थाओं को विवरण,
|
||||
आरेख व्याख्या या चार्ट डेटा निष्कर्षण के लिए एक विज़न मॉडल में रूट करें
|
||||
छवि विवरण को टेक्स्ट चाइल्ड दस्तावेज़ों के रूप में संग्रहीत करें जो
|
||||
मानक चंकिंग/निष्कर्षण पाइपलाइन में फीड करते हैं
|
||||
निकाले गए ज्ञान को प्रामाणिकता के माध्यम से स्रोत छवियों से लिंक करें
|
||||
|
||||
### अनुभाग रणनीतियाँ
|
||||
|
||||
पृष्ठ-आधारित प्रारूपों (पीडीएफ, पीपीटीएक्स, एक्सएलएसएक्स) के लिए, तत्वों को हमेशा
|
||||
पहले पृष्ठ/स्लाइड/शीट द्वारा समूहीकृत किया जाता है। गैर-पृष्ठ प्रारूपों (डीओसीएक्स, एचटीएमएल, मार्कडाउन,
|
||||
आदि) के लिए, डिकोडर को दस्तावेज़ को अनुभागों में विभाजित करने के लिए एक रणनीति की आवश्यकता होती है। यह ⟦CODE_0⟧ के माध्यम से रनटाइम पर कॉन्फ़िगर करने योग्य है।
|
||||
अनुभाग। यह `--section-strategy` के माध्यम से रनटाइम पर कॉन्फ़िगर किया जा सकता है।
|
||||
|
||||
प्रत्येक रणनीति `unstructured` तत्वों की सूची पर एक समूहीकरण फ़ंक्शन है। आउटपुट तत्वों के समूहों की एक सूची है; बाकी
|
||||
तत्व। आउटपुट तत्वों के समूहों की एक सूची है; बाकी का
|
||||
पाइपलाइन (टेक्स्ट असेंबली, लाइब्रेरियन स्टोरेज, प्रामाणिकता, टेक्स्टडॉक्यूमेंट
|
||||
उत्सर्जन) रणनीति की परवाह किए बिना समान है।
|
||||
|
||||
#### `whole-document` (डिफ़ॉल्ट)
|
||||
|
||||
पूरे दस्तावेज़ को एक ही अनुभाग के रूप में उत्सर्जित करें। डाउनस्ट्रीम
|
||||
चंकर को सभी विभाजन को संभालने दें।
|
||||
|
||||
सबसे सरल दृष्टिकोण, अच्छा आधार रेखा
|
||||
बड़ी फ़ाइलों के लिए बहुत बड़ा टेक्स्टडॉक्यूमेंट उत्पन्न कर सकता है, लेकिन चंकर
|
||||
इसे संभालता है
|
||||
जब आप प्रति अनुभाग अधिकतम संदर्भ चाहते हैं तो सबसे अच्छा
|
||||
|
||||
#### `heading`
|
||||
|
||||
शीर्षलेख तत्वों (`Title`) पर विभाजित करें। प्रत्येक अनुभाग एक शीर्षलेख प्लस
|
||||
सभी सामग्री है जब तक कि समान या उच्च स्तर का अगला शीर्षलेख न हो। नेस्टेड
|
||||
शीर्षलेख नेस्टेड अनुभाग बनाते हैं।
|
||||
|
||||
विषयगत रूप से सुसंगत इकाइयाँ उत्पन्न करता है
|
||||
संरचित दस्तावेज़ों (रिपोर्ट, मैनुअल, विनिर्देश) के लिए अच्छा काम करता है
|
||||
निष्कर्षण एलएलएम को सामग्री के साथ शीर्षलेख संदर्भ देता है
|
||||
यदि कोई शीर्षलेख नहीं मिला है तो `whole-document` पर वापस आ जाता है
|
||||
|
||||
#### `element-type`
|
||||
|
||||
जब तत्व प्रकार में महत्वपूर्ण परिवर्तन होता है तो विभाजित करें - विशेष रूप से,
|
||||
वर्णनात्मक पाठ और तालिकाओं के बीच संक्रमण पर एक नया अनुभाग शुरू करें। लगातार
|
||||
समान व्यापक श्रेणी (पाठ, पाठ, पाठ या
|
||||
तालिका, तालिका) के तत्व एक साथ समूहीकृत रहते हैं।
|
||||
|
||||
तालिकाओं को स्टैंडअलोन अनुभागों के रूप में रखता है
|
||||
मिश्रित सामग्री वाले दस्तावेज़ों (डेटा तालिकाओं वाली रिपोर्ट) के लिए अच्छा है
|
||||
तालिकाओं को समर्पित निष्कर्षण ध्यान मिलता है
|
||||
|
||||
#### `count`
|
||||
|
||||
तत्वों की एक निश्चित संख्या को प्रति अनुभाग समूहीकृत करें। ⟦CODE_0⟧ के माध्यम से कॉन्फ़िगर करने योग्य (डिफ़ॉल्ट: 20)।
|
||||
`--section-element-count` (डिफ़ॉल्ट: 20)।
|
||||
|
||||
सरल और अनुमानित
|
||||
दस्तावेज़ संरचना का सम्मान नहीं करता है
|
||||
प्रयोग के लिए एक फ़ॉलबैक या उपयोगी
|
||||
|
||||
#### `size`
|
||||
|
||||
तत्वों को तब तक जमा करें जब तक कि एक वर्ण सीमा तक न पहुँच जाए, फिर एक नया अनुभाग शुरू करें। तत्वों की सीमाओं का सम्मान करता है - कभी भी किसी तत्व के बीच में विभाजन नहीं करता है।
|
||||
नए अनुभाग। तत्वों की सीमाओं का सम्मान करता है - कभी भी किसी तत्व के बीच में विभाजन नहीं करता है।
|
||||
`--section-max-size` के माध्यम से कॉन्फ़िगर किया जा सकता है (डिफ़ॉल्ट: 4000 अक्षर)।
|
||||
|
||||
लगभग समान खंड आकार उत्पन्न करता है।
|
||||
तत्वों की सीमाओं का सम्मान करता है (डाउनस्ट्रीम चंकर के विपरीत)।
|
||||
संरचना और आकार नियंत्रण के बीच एक अच्छा समझौता।
|
||||
यदि कोई एकल तत्व सीमा से अधिक है, तो वह अपने आप में एक खंड बन जाता है।
|
||||
|
||||
#### पृष्ठ-आधारित प्रारूप इंटरैक्शन
|
||||
|
||||
पृष्ठ-आधारित स्वरूपों के लिए, पृष्ठ समूहीकरण हमेशा प्राथमिकता लेता है।
|
||||
अनुभाग रणनीतियों को वैकल्पिक रूप से एक पृष्ठ के *अंदर* लागू किया जा सकता है यदि वह बहुत बड़ा है (उदाहरण के लिए, एक बहुत बड़े तालिका वाला पीडीएफ पृष्ठ), जिसे द्वारा नियंत्रित किया जाता है।
|
||||
बड़ा (उदाहरण के लिए, एक पीडीएफ पृष्ठ जिसमें एक बहुत बड़ा तालिका है), जिसे नियंत्रित किया जाता है।
|
||||
`--section-within-pages` (डिफ़ॉल्ट: गलत)। जब गलत होता है, तो प्रत्येक पृष्ठ का
|
||||
आकार की परवाह किए बिना हमेशा एक ही खंड होता है।
|
||||
|
||||
### प्रारूप का पता लगाना
|
||||
|
||||
डीकोडर को दस्तावेज़ के एमआईएमई प्रकार के बारे में पता होना चाहिए ताकि इसे आगे बढ़ाया जा सके।
|
||||
`unstructured` का `partition()`। दो रास्ते:
|
||||
|
||||
**लाइब्रेरियन पथ** (`document_id` सेट): दस्तावेज़ मेटाडेटा प्राप्त करें।
|
||||
सबसे पहले लाइब्रेरियन से जानकारी प्राप्त करें - यह हमें `kind` (मिम टाइप) देता है।
|
||||
जो अपलोड के समय दर्ज किया गया था। फिर दस्तावेज़ सामग्री प्राप्त करें।
|
||||
दो लाइब्रेरियन कॉल, लेकिन मेटाडेटा प्राप्त करना आसान है।
|
||||
**इनलाइन पथ** (पिछला संगतता, `data` सेट): संदेश पर कोई मेटाडेटा उपलब्ध नहीं है।
|
||||
प्रारूप का पता लगाने के लिए `python-magic` का उपयोग करें।
|
||||
सामग्री बाइट्स से एक वैकल्पिक विधि के रूप में।
|
||||
|
||||
`Document` स्कीमा में कोई बदलाव आवश्यक नहीं है - लाइब्रेरियन पहले से ही MIME प्रकार संग्रहीत करता है।
|
||||
|
||||
|
||||
### वास्तुकला
|
||||
|
||||
एक एकल `universal-decoder` सेवा जो:
|
||||
|
||||
1. एक `Document` संदेश प्राप्त होता है (इनलाइन या लाइब्रेरियन संदर्भ के माध्यम से)।
|
||||
2. यदि लाइब्रेरियन पथ है: दस्तावेज़ मेटाडेटा प्राप्त करें (मिम प्रकार प्राप्त करें), फिर
|
||||
सामग्री प्राप्त करें। यदि इनलाइन पथ है: सामग्री बाइट्स से प्रारूप का पता लगाएं।
|
||||
3. तत्वों को निकालने के लिए `partition()` को कॉल करता है।
|
||||
4. तत्वों को समूहीकृत करता है: पृष्ठ-आधारित प्रारूपों के लिए पृष्ठ द्वारा, गैर-पृष्ठ प्रारूपों के लिए कॉन्फ़िगर किए गए
|
||||
अनुभाग रणनीति द्वारा।
|
||||
5. प्रत्येक पृष्ठ/अनुभाग के लिए:
|
||||
एक `urn:page:{uuid}` या `urn:section:{uuid}` आईडी उत्पन्न करता है।
|
||||
पृष्ठ पाठ को असेंबल करता है: वर्णनात्मक पाठ को सादे पाठ के रूप में, तालिकाओं को HTML के रूप में,
|
||||
छवियों को छोड़ दिया जाता है।
|
||||
पृष्ठ पाठ के भीतर प्रत्येक तत्व के लिए वर्ण अद्ययनों की गणना करता है।
|
||||
लाइब्रेरियन में एक चाइल्ड दस्तावेज़ के रूप में सहेजता है।
|
||||
स्थिति संबंधी मेटाडेटा के साथ प्रामाणिकता ट्रिपल उत्सर्जित करता है।
|
||||
टुकड़ों में विभाजित करने के लिए `TextDocument` को आगे भेजता है।
|
||||
6. प्रत्येक छवि तत्व के लिए:
|
||||
एक `urn:image:{uuid}` आईडी उत्पन्न करता है।
|
||||
छवि डेटा को लाइब्रेरियन में एक चाइल्ड दस्तावेज़ के रूप में सहेजता है।
|
||||
प्रामाणिकता ट्रिपल उत्सर्जित करता है (केवल संग्रहीत, आगे नहीं भेजा गया)।
|
||||
|
||||
### प्रारूप प्रबंधन
|
||||
|
||||
| प्रारूप | MIME प्रकार | पृष्ठ-आधारित | नोट्स |
|
||||
|----------|------------------------------------|------------|--------------------------------|
|
||||
| PDF | application/pdf | हाँ | प्रति-पृष्ठ समूहीकरण |
|
||||
| DOCX | application/vnd.openxmlformats... | नहीं | अनुभाग रणनीति का उपयोग करता है |
|
||||
| PPTX | application/vnd.openxmlformats... | हाँ | प्रति-स्लाइड समूहीकरण |
|
||||
| XLSX/XLS | application/vnd.openxmlformats... | हाँ | प्रति-शीट समूहीकरण |
|
||||
| HTML | text/html | नहीं | अनुभाग रणनीति का उपयोग करता है |
|
||||
| Markdown | text/markdown | नहीं | अनुभाग रणनीति का उपयोग करता है |
|
||||
| सादा | text/plain | नहीं | अनुभाग रणनीति का उपयोग करता है |
|
||||
| CSV | text/csv | नहीं | अनुभाग रणनीति का उपयोग करता है |
|
||||
| RST | text/x-rst | नहीं | अनुभाग रणनीति का उपयोग करता है |
|
||||
| RTF | application/rtf | नहीं | अनुभाग रणनीति का उपयोग करता है |
|
||||
| ODT | application/vnd.oasis... | नहीं | अनुभाग रणनीति का उपयोग करता है |
|
||||
| TSV | text/tab-separated-values | नहीं | अनुभाग रणनीति का उपयोग करता है |
|
||||
|
||||
### उत्पत्ति मेटाडेटा
|
||||
|
||||
प्रत्येक पृष्ठ/अनुभाग इकाई, प्रामाणिकता के रूप में स्थिति संबंधी मेटाडेटा को रिकॉर्ड करती है।
|
||||
`GRAPH_SOURCE` में ट्रिपल, जो नॉलेज ग्राफ (KG) ट्रिपल से स्रोत दस्तावेज़ की स्थिति तक पूर्ण पता लगाने की क्षमता प्रदान करते हैं।
|
||||
|
||||
|
||||
#### मौजूदा फ़ील्ड (पहले से ही `derived_entity_triples` में)
|
||||
|
||||
`page_number` — पृष्ठ/शीट/स्लाइड संख्या (1 से शुरू, केवल पृष्ठ-आधारित)
|
||||
`char_offset` — इस पृष्ठ/खंड के भीतर का वर्ण ऑफ़सेट।
|
||||
पूर्ण दस्तावेज़ पाठ
|
||||
`char_length` — इस पृष्ठ/खंड के पाठ की वर्ण संख्या
|
||||
|
||||
#### नए फ़ील्ड (`derived_entity_triples` का विस्तार करें)
|
||||
|
||||
`mime_type` — मूल दस्तावेज़ का प्रारूप (उदाहरण के लिए, `application/pdf`)
|
||||
`element_types` — `unstructured` तत्वों की अल्पविराम-विभाजित सूची
|
||||
इस पृष्ठ/अनुभाग में पाए गए श्रेणियाँ (उदाहरण के लिए, "शीर्षक, वर्णनात्मक पाठ, तालिका")
|
||||
`table_count` — इस पृष्ठ/अनुभाग में तालिकाओं की संख्या
|
||||
`image_count` — इस पृष्ठ/अनुभाग में छवियों की संख्या
|
||||
|
||||
इनके लिए नए टीजी नेमस्पेस विधेयकों की आवश्यकता है:
|
||||
|
||||
```
|
||||
TG_SECTION_TYPE = "https://trustgraph.ai/ns/Section"
|
||||
TG_IMAGE_TYPE = "https://trustgraph.ai/ns/Image"
|
||||
TG_ELEMENT_TYPES = "https://trustgraph.ai/ns/elementTypes"
|
||||
TG_TABLE_COUNT = "https://trustgraph.ai/ns/tableCount"
|
||||
TG_IMAGE_COUNT = "https://trustgraph.ai/ns/imageCount"
|
||||
```
|
||||
|
||||
इमेज यूआरएन योजना: `urn:image:{uuid}`
|
||||
|
||||
(`TG_MIME_TYPE` पहले से मौजूद है।)
|
||||
|
||||
#### नया इकाई प्रकार
|
||||
|
||||
गैर-पेज प्रारूपों (DOCX, HTML, Markdown, आदि) के लिए जहां डिकोडर
|
||||
पूरे दस्तावेज़ को एक इकाई के रूप में उत्सर्जित करता है, न कि पृष्ठों में विभाजित करके,
|
||||
इकाई को एक नया प्रकार मिलता है:
|
||||
|
||||
```
|
||||
TG_SECTION_TYPE = "https://trustgraph.ai/ns/Section"
|
||||
```
|
||||
|
||||
यह अनुभागों को पृष्ठों से अलग करता है जब मूल जानकारी प्राप्त करने के लिए क्वेरी की जाती है:
|
||||
|
||||
| इकाई | प्रकार | उपयोग कब |
|
||||
|---|---|---|
|
||||
| दस्तावेज़ | `tg:Document` | मूल अपलोड की गई फ़ाइल |
|
||||
| पृष्ठ | `tg:Page` | पृष्ठ-आधारित प्रारूप (पीडीएफ, पीपीटीएक्स, एक्सएलएसएक्स) |
|
||||
| अनुभाग | `tg:Section` | गैर-पृष्ठ प्रारूप (डीओएक्स, एचटीएमएल, एमडी, आदि) |
|
||||
| छवि | `tg:Image` | एम्बेडेड छवियां (संग्रहित, संसाधित नहीं) |
|
||||
| भाग | `tg:Chunk` | चंकर का आउटपुट |
|
||||
| उपग्राफ | `tg:Subgraph` | केजी निष्कर्षण आउटपुट |
|
||||
|
||||
प्रकार को डिकोडर द्वारा यह निर्धारित किया जाता है कि यह पृष्ठ द्वारा समूहीकृत है या पूरे दस्तावेज़ अनुभाग को उत्सर्जित कर रहा है। ⟦CODE_0⟧ प्राप्त होता है।
|
||||
या पूरे दस्तावेज़ अनुभाग को उत्सर्जित कर रहा है। `derived_entity_triples` प्राप्त होता है।
|
||||
एक वैकल्पिक `section` बूलियन पैरामीटर - जब सत्य होता है, तो इकाई को
|
||||
`tg:Section` के रूप में टाइप किया जाता है, `tg:Page` के बजाय।
|
||||
|
||||
#### पूर्ण उत्पत्ति श्रृंखला
|
||||
|
||||
```
|
||||
KG triple
|
||||
→ subgraph (extraction provenance)
|
||||
→ chunk (char_offset, char_length within page)
|
||||
→ page/section (page_number, char_offset, char_length within doc, mime_type, element_types)
|
||||
→ document (original file in librarian)
|
||||
```
|
||||
|
||||
प्रत्येक लिंक, `GRAPH_SOURCE` नामक ग्राफ में ट्रिपल के एक सेट का प्रतिनिधित्व करता है।
|
||||
|
||||
### सेवा कॉन्फ़िगरेशन
|
||||
|
||||
कमांड-लाइन तर्क:
|
||||
|
||||
```
|
||||
--strategy Partitioning strategy: auto, hi_res, fast (default: auto)
|
||||
--languages Comma-separated OCR language codes (default: eng)
|
||||
--section-strategy Section grouping: whole-document, heading, element-type,
|
||||
count, size (default: whole-document)
|
||||
--section-element-count Elements per section for 'count' strategy (default: 20)
|
||||
--section-max-size Max chars per section for 'size' strategy (default: 4000)
|
||||
--section-within-pages Apply section strategy within pages too (default: false)
|
||||
```
|
||||
|
||||
साथ ही मानक `FlowProcessor` और लाइब्रेरियन क्यू तर्क।
|
||||
|
||||
### फ्लो इंटीग्रेशन (प्रवाह एकीकरण)
|
||||
|
||||
सार्वभौमिक डिकोडर प्रसंस्करण प्रवाह में उसी स्थिति पर होता है
|
||||
जैसा कि वर्तमान पीडीएफ डिकोडर:
|
||||
|
||||
```
|
||||
Document → [universal-decoder] → TextDocument → [chunker] → Chunk → ...
|
||||
```
|
||||
|
||||
यह पंजीकृत करता है:
|
||||
`input` उपभोक्ता (दस्तावेज़ स्कीमा)
|
||||
`output` उत्पादक (टेक्स्टडॉक्यूमेंट स्कीमा)
|
||||
`triples` उत्पादक (ट्रिपल्स स्कीमा)
|
||||
लाइब्रेरियन अनुरोध/प्रतिक्रिया (फ़ेच और चाइल्ड दस्तावेज़ भंडारण के लिए)
|
||||
|
||||
### परिनियोजन
|
||||
|
||||
नया कंटेनर: `trustgraph-flow-universal-decoder`
|
||||
निर्भरता: `unstructured[all-docs]` (इसमें पीडीएफ, डॉक्स, पीपीटीएक्स, आदि शामिल हैं)
|
||||
यह मौजूदा पीडीएफ डिकोडर के साथ समानांतर रूप से चल सकता है या उसकी जगह ले सकता है, यह इस बात पर निर्भर करता है।
|
||||
प्रवाह विन्यास
|
||||
मौजूदा पीडीएफ डिकोडर उन वातावरणों में भी उपलब्ध रहेगा जहाँ
|
||||
`unstructured` निर्भरताएँ बहुत अधिक हैं
|
||||
|
||||
### क्या बदलाव
|
||||
|
||||
| घटक (Component) | परिवर्तन (Change) |
|
||||
|------------------------------|-------------------------------------------------|
|
||||
| `provenance/namespaces.py` | `TG_SECTION_TYPE`, `TG_IMAGE_TYPE`, `TG_ELEMENT_TYPES`, `TG_TABLE_COUNT`, `TG_IMAGE_COUNT` जोड़ें (Add `TG_SECTION_TYPE`, `TG_IMAGE_TYPE`, `TG_ELEMENT_TYPES`, `TG_TABLE_COUNT`, `TG_IMAGE_COUNT`) |
|
||||
| `provenance/triples.py` | `mime_type`, `element_types`, `table_count`, `image_count` kwargs जोड़ें (Add `mime_type`, `element_types`, `table_count`, `image_count` kwargs) |
|
||||
| `provenance/__init__.py` | नए स्थिरांकों को निर्यात करें (Export new constants) |
|
||||
| नया: `decoding/universal/` | नया डिकोडर सेवा मॉड्यूल (New decoder service module) |
|
||||
| `setup.cfg` / `pyproject` | `unstructured[all-docs]` निर्भरता जोड़ें (Add `unstructured[all-docs]` dependency) |
|
||||
| डॉकर (Docker) | नया कंटेनर इमेज (New container image) |
|
||||
| फ्लो परिभाषाएँ (Flow definitions) | यूनिवर्सल-डिकोडर को दस्तावेज़ इनपुट के रूप में उपयोग करें (Wire universal-decoder as document input) |
|
||||
|
||||
### क्या नहीं बदलता (What Doesn't Change)
|
||||
|
||||
चंकर (टेक्स्टडॉक्यूमेंट प्राप्त करता है, पहले की तरह काम करता है)
|
||||
डाउनस्ट्रीम एक्सट्रैक्टर (चंक प्राप्त करते हैं, अपरिवर्तित)
|
||||
लाइब्रेरियन (चाइल्ड डॉक्यूमेंट्स को संग्रहीत करता है, अपरिवर्तित)
|
||||
स्कीमा (डॉक्यूमेंट, टेक्स्टडॉक्यूमेंट, चंक अपरिवर्तित)
|
||||
क्वेरी-टाइम प्रोवेनेंस (अपरिवर्तित)
|
||||
|
||||
## जोखिम
|
||||
|
||||
`unstructured[all-docs]` में भारी निर्भरताएँ हैं (पोप्लर, टेसेरैक्ट,
|
||||
लिब्रेऑफिस कुछ प्रारूपों के लिए)। कंटेनर इमेज का आकार बड़ा होगा।
|
||||
निवारण: ओसीआर/ऑफिस निर्भरताओं के बिना `[light]` का एक संस्करण प्रदान करें।
|
||||
कुछ प्रारूपों से खराब टेक्स्ट निष्कर्षण हो सकता है (बिना ओसीआर वाले स्कैन किए गए पीडीएफ)।
|
||||
ओसीआर, जटिल एक्सेल (XLSX) लेआउट)। निवारण: कॉन्फ़िगर करने योग्य `strategy`
|
||||
पैरामीटर, और मौजूदा मिस्ट्रल ओसीआर डिकोडर अभी भी उपलब्ध है।
|
||||
उच्च-गुणवत्ता वाले पीडीएफ ओसीआर के लिए।
|
||||
`unstructured` संस्करण अपडेट से तत्व मेटाडेटा में परिवर्तन हो सकता है।
|
||||
निवारण: संस्करण को स्थिर करें, प्रत्येक प्रारूप के लिए निष्कर्षण गुणवत्ता का परीक्षण करें।
|
||||
307
docs/tech-specs/hi/vector-store-lifecycle.hi.md
Normal file
307
docs/tech-specs/hi/vector-store-lifecycle.hi.md
Normal file
|
|
@ -0,0 +1,307 @@
|
|||
---
|
||||
layout: default
|
||||
title: "वेक्टर स्टोर लाइफसाइकिल प्रबंधन"
|
||||
parent: "Hindi (Beta)"
|
||||
---
|
||||
|
||||
# वेक्टर स्टोर लाइफसाइकिल प्रबंधन
|
||||
|
||||
> **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.
|
||||
|
||||
## अवलोकन
|
||||
|
||||
यह दस्तावेज़ बताता है कि ट्रस्टग्राफ विभिन्न बैकएंड कार्यान्वयन (क्यूड्रेंट, पाइनकोन, मिल्वस) में वेक्टर स्टोर संग्रहों का प्रबंधन कैसे करता है। डिज़ाइन विभिन्न आयामों वाले एम्बेडिंग का समर्थन करने की चुनौती को संबोधित करता है बिना आयाम मानों को हार्डकोड किए।
|
||||
|
||||
## समस्या विवरण
|
||||
|
||||
वेक्टर स्टोर को संग्रह/इंडेक्स बनाते समय एम्बेडिंग आयाम को निर्दिष्ट करने की आवश्यकता होती है। हालाँकि:
|
||||
विभिन्न एम्बेडिंग मॉडल अलग-अलग आयाम उत्पन्न करते हैं (उदाहरण के लिए, 384, 768, 1536)
|
||||
आयाम तब तक ज्ञात नहीं होता है जब तक कि पहला एम्बेडिंग उत्पन्न नहीं हो जाता
|
||||
एक ही ट्रस्टग्राफ संग्रह कई मॉडलों से एम्बेडिंग प्राप्त कर सकता है
|
||||
एक आयाम को हार्डकोड करना (उदाहरण के लिए, 384) अन्य एम्बेडिंग आकारों के साथ विफलताओं का कारण बनता है
|
||||
|
||||
## डिज़ाइन सिद्धांत
|
||||
|
||||
1. **आलसी निर्माण**: संग्रह पहली बार लिखने के दौरान ऑन-डिमांड बनाए जाते हैं, संग्रह प्रबंधन कार्यों के दौरान नहीं।
|
||||
2. **आयाम-आधारित नामकरण**: संग्रह नामों में एम्बेडिंग आयाम को एक प्रत्यय के रूप में शामिल किया जाता है।
|
||||
3. **सुचारू गिरावट**: गैर-मौजूदा संग्रहों के खिलाफ किए गए प्रश्नों से त्रुटियां नहीं, बल्कि खाली परिणाम मिलते हैं।
|
||||
4. **बहु-आयाम समर्थन**: एक ही तार्किक संग्रह में कई भौतिक संग्रह (प्रत्येक आयाम के लिए एक) हो सकते हैं।
|
||||
|
||||
## वास्तुकला
|
||||
|
||||
### संग्रह नामकरण सम्मेलन
|
||||
|
||||
वेक्टर स्टोर संग्रह कई एम्बेडिंग आकारों का समर्थन करने के लिए आयाम प्रत्ययों का उपयोग करते हैं:
|
||||
|
||||
**दस्तावेज़ एम्बेडिंग:**
|
||||
क्यूड्रेंट: `d_{user}_{collection}_{dimension}`
|
||||
पाइनकोन: `d-{user}-{collection}-{dimension}`
|
||||
मिल्वस: `doc_{user}_{collection}_{dimension}`
|
||||
|
||||
**ग्राफ एम्बेडिंग:**
|
||||
क्यूड्रेंट: `t_{user}_{collection}_{dimension}`
|
||||
पाइनकोन: `t-{user}-{collection}-{dimension}`
|
||||
मिल्वस: `entity_{user}_{collection}_{dimension}`
|
||||
|
||||
उदाहरण:
|
||||
`d_alice_papers_384` - 384-आयामी एम्बेडिंग वाले एलिस के पेपर संग्रह
|
||||
`d_alice_papers_768` - 768-आयामी एम्बेडिंग वाले समान तार्किक संग्रह
|
||||
`t_bob_knowledge_1536` - 1536-आयामी एम्बेडिंग वाले बॉब के ज्ञान ग्राफ
|
||||
|
||||
### जीवनचक्र चरण
|
||||
|
||||
#### 1. संग्रह निर्माण अनुरोध
|
||||
|
||||
**अनुरोध प्रवाह:**
|
||||
```
|
||||
User/System → Librarian → Storage Management Topic → Vector Stores
|
||||
```
|
||||
|
||||
**व्यवहार:**
|
||||
लाइब्रेरियन `create-collection` अनुरोधों को सभी स्टोरेज बैकएंड्स को भेजता है।
|
||||
वेक्टर स्टोर प्रोसेसर अनुरोध को स्वीकार करते हैं लेकिन **भौतिक संग्रह नहीं बनाते हैं।**
|
||||
प्रतिक्रिया तुरंत सफलता के साथ वापस की जाती है।
|
||||
वास्तविक संग्रह निर्माण पहले लिखने तक स्थगित रहता है।
|
||||
|
||||
**तर्क:**
|
||||
निर्माण के समय आयाम अज्ञात होता है।
|
||||
गलत आयाम वाले संग्रह बनाने से बचा जाता है।
|
||||
संग्रह प्रबंधन तर्क को सरल बनाता है।
|
||||
|
||||
#### 2. लेखन संचालन (आलसी निर्माण)
|
||||
|
||||
**लेखन प्रवाह:**
|
||||
```
|
||||
Data → Storage Processor → Check Collection → Create if Needed → Insert
|
||||
```
|
||||
|
||||
**व्यवहार:**
|
||||
1. वेक्टर से एम्बेडिंग आयाम निकालें: `dim = len(vector)`
|
||||
2. आयाम प्रत्यय के साथ संग्रह का नाम बनाएं
|
||||
3. जांचें कि क्या उस विशिष्ट आयाम के साथ कोई संग्रह मौजूद है
|
||||
4. यदि मौजूद नहीं है:
|
||||
सही आयाम के साथ संग्रह बनाएं
|
||||
लॉग करें: `"Lazily creating collection {name} with dimension {dim}"`
|
||||
5. एम्बेडिंग को आयाम-विशिष्ट संग्रह में डालें
|
||||
|
||||
**उदाहरण परिदृश्य:**
|
||||
```
|
||||
1. User creates collection "papers"
|
||||
→ No physical collections created yet
|
||||
|
||||
2. First document with 384-dim embedding arrives
|
||||
→ Creates d_user_papers_384
|
||||
→ Inserts data
|
||||
|
||||
3. Second document with 768-dim embedding arrives
|
||||
→ Creates d_user_papers_768
|
||||
→ Inserts data
|
||||
|
||||
Result: Two physical collections for one logical collection
|
||||
```
|
||||
|
||||
#### 3. क्वेरी ऑपरेशन
|
||||
|
||||
**क्वेरी प्रवाह:**
|
||||
```
|
||||
Query Vector → Determine Dimension → Check Collection → Search or Return Empty
|
||||
```
|
||||
|
||||
**व्यवहार:**
|
||||
1. क्वेरी वेक्टर से आयाम निकालें: `dim = len(vector)`
|
||||
2. आयाम प्रत्यय के साथ संग्रह नाम बनाएं
|
||||
3. जांचें कि संग्रह मौजूद है या नहीं
|
||||
4. यदि मौजूद है:
|
||||
समानता खोज करें
|
||||
परिणाम लौटाएं
|
||||
5. यदि मौजूद नहीं है:
|
||||
लॉग करें: `"Collection {name} does not exist, returning empty results"`
|
||||
खाली सूची लौटाएं (कोई त्रुटि नहीं)
|
||||
|
||||
**एक ही क्वेरी में कई आयाम:**
|
||||
यदि क्वेरी में विभिन्न आयामों वाले वेक्टर हैं
|
||||
प्रत्येक आयाम अपने संबंधित संग्रह को क्वेरी करता है
|
||||
परिणाम एकत्रित किए जाते हैं
|
||||
गुम संग्रह को छोड़ दिया जाता है (त्रुटियों के रूप में नहीं माना जाता है)
|
||||
|
||||
**तर्क:**
|
||||
एक खाली संग्रह को क्वेरी करना एक वैध उपयोग मामला है
|
||||
खाली परिणाम लौटाना अर्थपूर्ण रूप से सही है
|
||||
सिस्टम स्टार्टअप के दौरान या डेटा इनपुट से पहले त्रुटियों से बचाता है
|
||||
|
||||
#### 4. संग्रह हटाना
|
||||
|
||||
**हटाने की प्रक्रिया:**
|
||||
```
|
||||
Delete Request → List All Collections → Filter by Prefix → Delete All Matches
|
||||
```
|
||||
|
||||
**व्यवहार:**
|
||||
1. उपसर्ग पैटर्न का निर्माण करें: `d_{user}_{collection}_` (अंतिम अंडरस्कोर पर ध्यान दें)
|
||||
2. वेक्टर स्टोर में सभी संग्रहों की सूची बनाएं
|
||||
3. उपसर्ग से मेल खाने वाले संग्रहों को फ़िल्टर करें
|
||||
4. सभी मेल खाने वाले संग्रहों को हटाएं
|
||||
5. प्रत्येक हटाने को लॉग करें: `"Deleted collection {name}"`
|
||||
6. सारांश लॉग: `"Deleted {count} collection(s) for {user}/{collection}"`
|
||||
|
||||
**उदाहरण:**
|
||||
```
|
||||
Collections in store:
|
||||
- d_alice_papers_384
|
||||
- d_alice_papers_768
|
||||
- d_alice_reports_384
|
||||
- d_bob_papers_384
|
||||
|
||||
Delete "papers" for alice:
|
||||
→ Deletes: d_alice_papers_384, d_alice_papers_768
|
||||
→ Keeps: d_alice_reports_384, d_bob_papers_384
|
||||
```
|
||||
|
||||
**तर्क:**
|
||||
सभी आयाम रूपों की पूरी तरह से सफाई सुनिश्चित करता है।
|
||||
पैटर्न मिलान से असंबंधित संग्रहों को गलती से हटाने से रोका जाता है।
|
||||
उपयोगकर्ता के दृष्टिकोण से परमाणु ऑपरेशन (सभी आयाम एक साथ हटा दिए जाते हैं)।
|
||||
|
||||
## व्यवहार संबंधी विशेषताएं
|
||||
|
||||
### सामान्य संचालन
|
||||
|
||||
**संग्रह निर्माण:**
|
||||
✓ तुरंत सफलता देता है।
|
||||
✓ कोई भौतिक भंडारण आवंटित नहीं किया जाता है।
|
||||
✓ तेज़ ऑपरेशन (कोई बैकएंड I/O नहीं)।
|
||||
|
||||
**पहला लेखन:**
|
||||
✓ सही आयाम के साथ संग्रह बनाता है।
|
||||
✓ संग्रह निर्माण के ओवरहेड के कारण थोड़ा धीमा।
|
||||
✓ उसी आयाम में बाद के लेखन तेज़ होते हैं।
|
||||
|
||||
**किसी भी लेखन से पहले प्रश्न:**
|
||||
✓ खाली परिणाम देता है।
|
||||
✓ कोई त्रुटि या अपवाद नहीं।
|
||||
✓ सिस्टम स्थिर रहता है।
|
||||
|
||||
**मिश्रित आयाम लेखन:**
|
||||
✓ स्वचालित रूप से प्रत्येक आयाम के लिए अलग-अलग संग्रह बनाता है।
|
||||
✓ प्रत्येक आयाम अपने स्वयं के संग्रह में अलग-थलग होता है।
|
||||
✓ कोई आयाम संघर्ष या स्कीमा त्रुटि नहीं होती है।
|
||||
|
||||
**संग्रह हटाना:**
|
||||
✓ सभी आयाम रूपों को हटा देता है।
|
||||
✓ पूर्ण सफाई।
|
||||
✓ कोई अनाथ संग्रह नहीं।
|
||||
|
||||
### विशेष स्थितियाँ
|
||||
|
||||
**एकाधिक एम्बेडिंग मॉडल:**
|
||||
```
|
||||
Scenario: User switches from model A (384-dim) to model B (768-dim)
|
||||
Behavior:
|
||||
- Both dimensions coexist in separate collections
|
||||
- Old data (384-dim) remains queryable with 384-dim vectors
|
||||
- New data (768-dim) queryable with 768-dim vectors
|
||||
- Cross-dimension queries return results only for matching dimension
|
||||
```
|
||||
|
||||
**एक साथ प्रारंभिक लेखन:**
|
||||
```
|
||||
Scenario: Multiple processes write to same collection simultaneously
|
||||
Behavior:
|
||||
- Each process checks for existence before creating
|
||||
- Most vector stores handle concurrent creation gracefully
|
||||
- If race condition occurs, second create is typically idempotent
|
||||
- Final state: Collection exists and both writes succeed
|
||||
```
|
||||
|
||||
**आयाम प्रवासन:**
|
||||
```
|
||||
Scenario: User wants to migrate from 384-dim to 768-dim embeddings
|
||||
Behavior:
|
||||
- No automatic migration
|
||||
- Old collection (384-dim) persists
|
||||
- New collection (768-dim) created on first new write
|
||||
- Both dimensions remain accessible
|
||||
- Manual deletion of old dimension collections possible
|
||||
```
|
||||
|
||||
**खाली संग्रह प्रश्नों:**
|
||||
```
|
||||
Scenario: Query a collection that has never received data
|
||||
Behavior:
|
||||
- Collection doesn't exist (never created)
|
||||
- Query returns empty list
|
||||
- No error state
|
||||
- System logs: "Collection does not exist, returning empty results"
|
||||
```
|
||||
|
||||
## कार्यान्वयन नोट्स
|
||||
|
||||
### स्टोरेज बैकएंड विशिष्ट विवरण
|
||||
|
||||
**Qdrant:**
|
||||
अस्तित्व जांच के लिए `collection_exists()` का उपयोग करता है
|
||||
हटाने के दौरान लिस्टिंग के लिए `get_collections()` का उपयोग करता है
|
||||
संग्रह निर्माण के लिए `VectorParams(size=dim, distance=Distance.COSINE)` की आवश्यकता होती है
|
||||
|
||||
**Pinecone:**
|
||||
अस्तित्व जांच के लिए `has_index()` का उपयोग करता है
|
||||
हटाने के दौरान लिस्टिंग के लिए `list_indexes()` का उपयोग करता है
|
||||
इंडेक्स निर्माण के लिए "तैयार" स्थिति की प्रतीक्षा करने की आवश्यकता होती है
|
||||
सर्वरलेस विनिर्देश क्लाउड/क्षेत्र के साथ कॉन्फ़िगर किया गया है
|
||||
|
||||
**Milvus:**
|
||||
डायरेक्ट क्लासेस (`DocVectors`, `EntityVectors`) लाइफसाइकिल का प्रबंधन करती हैं
|
||||
प्रदर्शन के लिए आंतरिक कैश `self.collections[(dim, user, collection)]`
|
||||
संग्रह नामों को सैनिटाइज किया जाता है (केवल अल्फ़ान्यूमेरिक + अंडरस्कोर)
|
||||
ऑटो-इंक्रीमेंटिंग आईडी के साथ स्कीमा का समर्थन करता है
|
||||
|
||||
### प्रदर्शन संबंधी विचार
|
||||
|
||||
**पहली लेखन विलंबता:**
|
||||
संग्रह निर्माण के कारण अतिरिक्त ओवरहेड
|
||||
Qdrant: ~100-500ms
|
||||
Pinecone: ~10-30 सेकंड (सर्वरलेस प्रावधान)
|
||||
Milvus: ~500-2000ms (इसमें इंडेक्सिंग शामिल है)
|
||||
|
||||
**क्वेरी प्रदर्शन:**
|
||||
अस्तित्व जांच से न्यूनतम ओवरहेड जुड़ता है (~1-10ms)
|
||||
एक बार संग्रह मौजूद होने पर कोई प्रदर्शन प्रभाव नहीं पड़ता है
|
||||
प्रत्येक आयाम संग्रह स्वतंत्र रूप से अनुकूलित है
|
||||
|
||||
**स्टोरेज ओवरहेड:**
|
||||
प्रति संग्रह न्यूनतम मेटाडेटा
|
||||
मुख्य ओवरहेड प्रति-आयाम स्टोरेज है
|
||||
ट्रेड-ऑफ: स्टोरेज स्पेस बनाम आयाम लचीलापन
|
||||
|
||||
## भविष्य के विचार
|
||||
|
||||
**स्वचालित आयाम समेकन:**
|
||||
अप्रयुक्त आयाम वेरिएंट की पहचान और विलय करने के लिए एक पृष्ठभूमि प्रक्रिया जोड़ी जा सकती है
|
||||
इसके लिए पुनः एम्बेडिंग या आयाम में कमी की आवश्यकता होगी
|
||||
|
||||
**आयाम खोज:**
|
||||
एक संग्रह के लिए उपयोग किए जा रहे सभी आयामों को सूचीबद्ध करने के लिए एपीआई उजागर किया जा सकता है
|
||||
प्रशासन और निगरानी के लिए उपयोगी
|
||||
|
||||
**डिफ़ॉल्ट आयाम प्राथमिकता:**
|
||||
प्रति संग्रह "प्राथमिक" आयाम को ट्रैक किया जा सकता है
|
||||
जब आयाम संदर्भ अनुपलब्ध हो तो प्रश्नों के लिए इसका उपयोग करें
|
||||
|
||||
**स्टोरेज कोटा:**
|
||||
प्रति-संग्रह आयाम सीमाएं आवश्यक हो सकती हैं
|
||||
आयाम वेरिएंट के प्रसार को रोकें
|
||||
|
||||
## माइग्रेशन नोट्स
|
||||
|
||||
**प्री-डायमेंशन-सफिक्स सिस्टम से:**
|
||||
पुराने संग्रह: `d_{user}_{collection}` (कोई आयाम प्रत्यय नहीं)
|
||||
नए संग्रह: `d_{user}_{collection}_{dim}` (आयाम प्रत्यय के साथ)
|
||||
कोई स्वचालित माइग्रेशन नहीं - पुराने संग्रह सुलभ रहते हैं
|
||||
यदि आवश्यक हो तो एक मैनुअल माइग्रेशन स्क्रिप्ट पर विचार करें
|
||||
दोनों नामकरण योजनाओं को एक साथ चलाया जा सकता है
|
||||
|
||||
## संदर्भ
|
||||
|
||||
संग्रह प्रबंधन: `docs/tech-specs/collection-management.md`
|
||||
स्टोरेज स्कीमा: `trustgraph-base/trustgraph/schema/services/storage.py`
|
||||
लाइब्रेरियन सेवा: `trustgraph-flow/trustgraph/librarian/service.py`
|
||||
Loading…
Add table
Add a link
Reference in a new issue