# Mfumo wa Uwekaji Njia (Flow Blueprint) - Vigezo Vinavyoweza Kubadilishwa - Maelezo ya Kiufundi
## Maelezo
Maelezo haya yanaeleza utekelezaji wa vigezo vinavyoweza kubadilishwa kwa mifumo ya uwekaji njia (flow blueprints) katika TrustGraph. Vigezo huruhusu watumiaji kubadilisha vigezo vya kichakato (processor) wakati wa kuanzisha mfumo wa uwekaji njia kwa kutoa maadili ambayo hubadilisha nafasi za vigezo katika ufafanuzi wa mfumo wa uwekaji njia.
Vigezo hufanya kazi kupitia ubadilishaji wa vigezo vya kishabaha katika vigezo vya kichakato, sawa na jinsi vigezo vya `{id}` na `{class}` hufanya kazi, lakini kwa maadili ambayo hutolewa na mtumiaji.
Vigezo hufanya kazi kupitia ubadilishaji wa vigezo vya kishabaha katika vigezo vya kichakato, sawa na jinsi vigezo `{id}` na `{class}` hufanya kazi, lakini kwa maadili ambayo hutolewa na mtumiaji.
Mifumo ya uwekaji njia katika TrustGraph sasa inaunga mkono vigezo vya kichakato ambavyo yanaweza kuwa na maadili thabiti au nafasi za vigezo. Hii huunda fursa ya urekebishaji wakati wa utendaji.
Mifumo ya uwekaji njia katika TrustGraph sasa inasaidia vigezo vya kichakato ambavyo yanaweza kuwa na maadili thabiti au nafasi za vigezo. Hii huunda fursa ya urekebishaji wakati wa utendaji.
Sehemu ya `parameters` inaeleza jina la kila parameter (funguo) inayohusiana na mtiririko, na inaunganisha na vitu vya metadata ya parameter ambavyo vina:
`type`: Rejea kwa ufafanuzi wa parameter uliotolewa kwa njia ya kati (k.m., "llm-model")
`description`: Maelezo ambayo yanaweza kusomwa na binadamu kwa ajili ya kuonyeshwa kwenye kiolesura (UI)
`order`: Mpangilio wa kuonyeshwa wa parameter katika fomu (nambari ndogo huonyeshwa kwanza)
`advanced` (hiari): Bendera ya boolean inayoelezea ikiwa hii ni parameter ya hali ya juu (ya kawaida: false). Ikiwa imewekwa kuwa "true", kiolesura kinaweza kuficha parameter hii kwa chagu ku, au kuiweka katika sehemu ya "Advanced"
`controlled-by` (hiari): Jina la parameter nyingine ambayo inadhibiti thamani ya parameter hii wakati katika hali rahisi. Ikiwa imeingizwa, parameter hii inaruhusu thamani yake kutoka kwa parameter inayodhibiti, isipokuwa ikiwa imebadilishwa wazi.
Mbinu hii inaruhusu:
Ufafanuzi wa aina ya parameter unaoweza kutumika tena katika mipangilio mingi.
Usimamizi na uthibitishaji wa aina ya parameter katika eneo moja.
Maelezo na mpangilio wa parameter unaohusiana na kila mtiririko.
Uzoefu bora wa kiolesura (UI) kwa kutumia fomu za parameter zenye maelezo.
Uthibitishaji thabiti wa parameter katika mitiririko yote.
Sehemu ya `parameters` inaeleza jina la parameter (funguo) inayohusiana na mtiririko, na inaunganisha na vitu vya metadata ya parameter ambavyo vina:
`type`: Rejea kwa ufafanuzi wa parameter uliotolewa kwa njia ya kati (k.m., "llm-model")
`description`: Maelezo ambayo yanaweza kusomwa na binadamu kwa ajili ya kuonyeshwa kwenye kiolesura (UI)
`order`: Mfululizo wa kuonyeshwa kwa fomu za parameter (nambari ndogo huonyeshwa kwanza)
`advanced` (hiari): Bendera ya Boolean inayoelezea ikiwa hii ni parameter ya hali ya juu (ya kawaida: false). Ikiwa imewekwa kuwa "true", kiolesura kinaweza kuficha parameter hii kwa chaguльку au kuiweka katika sehemu ya "Advanced"
`controlled-by` (hiari): Jina la parameter nyingine ambayo inadhibiti thamani ya parameter hii wakati katika hali rahisi. Ikiwa imeingizwa, parameter hii inaruhusu thamani yake kutoka kwa parameter inayodhibiti, isipokuwa ikiwa imebadilishwa wazi.
Mbinu hii inaruhusu:
Ufafanuzi wa aina ya parameter unaoweza kutumika tena katika mipangilio mingi ya mtiririko.
Usimamizi na uthibitishaji wa aina ya parameter unaozingatia.
Maelezo na mpangilio wa parameter unaozingatia mtiririko.
Uzoefu bora wa kiolesura (UI) na fomu za parameter zenye maelezo.
Uthibitishaji thabiti wa parameter katika mitiririko.
Kuongeza kwa urahisi aina mpya za parameter za kawaida.
Kiolesura kilichorahisishwa na mgawanyiko wa hali ya msingi/ya hali ya juu.
Urithi wa thamani ya parameter kwa mipangilio inayohusiana.
#### Ombi la Uzinduzi wa Mtiririko
API ya uzinduzi wa mtiririko inakubali parameter kwa kutumia majina ya parameter ya mtiririko:
```json
{
"flow_class": "document-analysis",
"flow_id": "customer-A-flow",
"parameters": {
"llm-model": "claude-3",
"llm-temperature": 0.5,
"chunk-size": 1024
}
}
```
Kumbuka: Katika mfano huu, `llm-rag-model` haitoa maelezo wazi lakini itapokea thamani "claude-3" kutoka kwa `llm-model` kutokana na uhusiano wake wa `controlled-by`. Vile vile, `chunk-overlap` inaweza kupokea thamani iliyohitajiwa kulingana na `chunk-size`.
Mfumo utafanya:
1. Kuchukua metadata ya vigezo kutoka ufafanuzi wa mpango (blueprint).
2. Kuunganisha majina ya vigezo vya mpango na ufafanuzi wao wa aina (e.g., `llm-model` → `llm-model` aina).
3. Kutatua uhusiano wa "controlled-by" (e.g., `llm-rag-model` inarithi kutoka kwa `llm-model`).
2.**Kuchukua Metadata**: Chukua `type`, `description`, `order`, `advanced`, na `controlled-by` kwa kila kiparamu kilichoainishwa katika sehemu ya `parameters` ya ufafanuzi wa mpango.
3.**Kutafuta Ufafanuzi wa Aina**: Kwa kila kiparamu katika ufafanuzi wa mpango:
Pata ufafanuzi wa aina ya kiparamu kutoka kwa duka la schema/config kwa kutumia sehemu ya `type`.
Ufafanuzi wa aina huhifadhiwa na aina "parameter-type" katika mfumo wa config.
Kila ufafanuzi wa aina una schema ya kiparamu, thamani ya chaguo-msingi, na sheria za uthibitishaji.
4.**Kutatua Thamani ya Chaguo-msingi**:
Kwa kila kiparamu kilichoainishwa katika ufafanuzi wa mpango:
Angalia ikiwa mtumiaji ametoa thamani kwa kiparamu hiki.
Ikiwa hakuna thamani iliyotolewa na mtumiaji, tumia thamani ya `default` kutoka kwa ufafanuzi wa aina ya kiparamu.
Unda ramani kamili ya vigezo inayojumuisha maadili yaliyotolewa na mtumiaji na maadili chaguo-msingi.
5.**Kutatua Ufuataji wa Vigezo** (uhusiano wa "controlled-by"):
Kwa vigezo vyenye sehemu ya `controlled-by`, angalia ikiwa thamani ilitolewa wazi.
Ikiwa hakuna thamani iliyotolewa wazi, arithia thamani kutoka kwa kiparamu kinachodhibiti.
Ikiwa kiparamu kinachodhibiti pia hakina thamani, tumia chaguo-msingi kutoka kwa ufafanuzi wa aina.
Hakikisha kuwa hakuna utegemezi wa mzunguko katika uhusiano wa `controlled-by`.
6.**Uthibitishaji**: Thibitisha seti kamili ya vigezo (vile vilivyotolewa na mtumiaji, chaguo-msingi, na vile vilivyorithiwa) dhidi ya ufafanuzi wa aina.
2.**Kuchukua Metadata**: Chukua `type`, `description`, `order`, `advanced`, na `controlled-by` kwa kila kigezo kilichoainishwa katika sehemu ya `parameters` ya ufafanuzi wa mpango.
3.**Kutafuta Ufafanuzi wa Aina**: Kwa kila kigezo katika ufafanuzi wa mpango:
Pata ufafanuzi wa aina ya kigezo kutoka kwa duka la schema/config kwa kutumia sehemu ya `type`.
Ufafanuzi wa aina huhifadhiwa na aina "parameter-type" katika mfumo wa config.
Kila ufafanuzi wa aina una schema ya kigezo, thamani ya chaguo-msingi, na sheria za uthibitishaji.
4.**Kutatua Thamani ya Chaguo-msingi**:
Kwa kila kigezo kilichoainishwa katika ufafanuzi wa mpango:
Angalia ikiwa mtumiaji ametoa thamani kwa kigezo hiki.
Ikiwa hakuna thamani iliyotolewa na mtumiaji, tumia thamani ya `default` kutoka kwa ufafanuzi wa aina ya kigezo.
Unda ramani kamili ya vigezo inayojumuisha maadili yaliyotolewa na mtumiaji na maadili chaguo-msingi.
5.**Kutatua Ufuasi wa Vigezo** (uhusiano wa "controlled-by"):
Kwa vigezo vyenye sehemu ya `controlled-by`, angalia ikiwa thamani ilitolewa wazi.
Ikiwa hakuna thamani iliyotolewa wazi, arithia thamani kutoka kwa kigezo kinachodhibiti.
Ikiwa kigezo kinachodhibiti pia hakina thamani, tumia chaguo-msingi kutoka kwa ufafanuzi wa aina.
Hakikisha kuwa hakuna utegemezi wa mzunguko katika uhusiano wa `controlled-by`.
6.**Uthibitishaji**: Thibitisha seti kamili ya vigezo (vile vilivyotolewa na mtumiaji, chaguo-msingi, na vile vilivyorithishwa) dhidi ya ufafanuzi wa aina.
Huduma ya mpango INAVYOHITAJI kuchanganya vigezo vilivyotolewa na mtumiaji na chaguo-msingi kutoka kwa ufafanuzi wa aina ya kiparamu.
Seti kamili ya vigezo (ikiwa ni pamoja na chaguo-msingi zilizotumiwa) INAVYOHITAJI kuhifadhiwa na mpango kwa ajili ya ufuatiliaji.
Kutatua vigezo hufanyika wakati wa kuanza kwa mpango, sio wakati wa kuunda kichakataji.
Vigezo muhimu ambavyo havina chaguo-msingi HAVIHUITAJI kusababisha kuanza kwa mpango kushindwa na ujumbe wa kosa wazi.
#### Ufuataji wa Vigezo na "controlled-by"
Sehemu ya `controlled-by` inaruhusu urithi wa thamani ya kiparamu, ambayo ni muhimu sana kwa kurahisisha mazingira ya mtumiaji huku ikiendelea kudumisha uwezekano:
**Mfano wa Matukio:**
Kiparamu cha `llm-model` kinadhibiti mfumo mkuu wa LLM.
Kiparamu cha `llm-rag-model` kina `"controlled-by": "llm-model"`.
Katika hali rahisi, kuweka `llm-model` kwa "gpt-4" huanzisha kiotomatiki `llm-rag-model` kwa "gpt-4" pia.
Katika hali ya juu, watumiaji wanaweza kubadilisha `llm-rag-model` na thamani tofauti.
**Sheria za Kutatua:**
1. Ikiwa kiparamu kina thamani iliyotolewa wazi, tumia thamani hiyo.
2. Ikiwa hakuna thamani iliyotolewa wazi na `controlled-by` imewekwa, tumia thamani ya kiparamu kinachodhibiti.
3. Ikiwa kiparamu kinachodhibiti hakina thamani, rudi kwenye chaguo-msingi kutoka kwa ufafanuzi wa aina.
4. Utendaji wa mzunguko katika uhusiano wa `controlled-by` husababisha kosa la uthibitishaji.
**Tabia ya UI:**
Katika hali ya msingi/rahisi: Vigezo vyenye `controlled-by` vinaweza kufichwa au kuonyeshwa kama visivyo na uwezo wa kubadilishwa na thamani iliyoarithi.
Katika hali ya juu: Vigezo vyote huonyeshwa na vinaweza kusanidiwa kivyake.
Huduma ya mpango INAVYOKWENDA kuchanganya vigezo vilivyotolewa na mtumiaji na chaguo-msingi kutoka kwa ufafanuzi wa aina ya kigezo.
Seti kamili ya vigezo (ikiwa ni pamoja na chaguo-msingi zilizotumiwa) INAVYOKWENDA kuhifadhiwa na mpango kwa ajili ya ufuatiliaji.
Kutatua vigezo hufanyika wakati wa kuanza kwa mpango, sio wakati wa kuunda kichakataji.
Vigezo muhimu ambavyo havina chaguo-msingi HAVI kukatisha kuanza kwa mpango na kuonyesha ujumbe wa kosa wazi.
#### Ufuasi wa Vigezo na "controlled-by"
Sehemu ya `controlled-by` inaruhusu urithi wa thamani ya kigezo, ambayo ni muhimu sana kwa kurahisisha mazingira ya mtumiaji huku ikiendelea kuwezesha utendaji:
**Mfano wa Matukio:**
Kigezo cha `llm-model` kinadhibiti mfumo mkuu wa LLM.
Kigezo cha `llm-rag-model` kina `"controlled-by": "llm-model"`.
Katika hali rahisi, kuweka `llm-model` kwa "gpt-4" hufanya `llm-rag-model` pia iwe "gpt-4" kiotomatiki.
Katika hali ya juu, watumiaji wanaweza kubadilisha `llm-rag-model` na thamani tofauti.
**Sheria za Kutatua:**
1. Ikiwa kigezo kina thamani iliyotolewa wazi, tumia thamani hiyo.
2. Ikiwa hakuna thamani iliyotolewa na `controlled-by` imewekwa, tumia thamani ya kigezo kinachodhibiti.
3. Ikiwa kigezo kinachodhibiti hakina thamani, rudi kwenye chaguo-msingi kutoka kwa ufafanuzi wa aina.
4. Utendaji wa mzunguko katika uhusiano wa `controlled-by` husababisha kosa la uthibitishaji.
**Tabia ya UI:**
Katika hali ya msingi/rahisi: Vigezo vyenye `controlled-by` vinaweza kufichwa au kuonyeshwa kama visivyo na uwezo (read-only) na thamani iliyoorithishwa.
Katika hali ya juu: Vigezo vyote huonyeshwa na vinaweza kusanidiwa kivyake.
Wakati kigezo kinachodhibiti kinapobadilika, vigezo vinavyotegemea hupatikana kiotomatiki isipokuwa ikiwa vimewekwa kuwa visivyo na uwezo.
Wakati mtiririko unaongezwa kwenye mfumo wa usanidi na kipengele cha mtiririko katika meneja wa usanidi, kitu cha mtiririko lazima kiwe na maadili yaliyomalizika ya vigezo
Meneja wa usanidi lazima ahifadhi vigezo vyote vilivyotolewa na mtumiaji na maadili yaliyomalizika (pamoja na maadili chaguo)
Vitu vya mtiririko katika mfumo wa usanidi vinapaswa kujumuisha:
`parameters`: Maadili ya vigezo yaliyomalizika ambayo hutumiwa kwa mtiririko
Wakati mtiririko unaongezwa kwenye mfumo wa usanidi na kipengele cha mtiririko katika meneja wa usanidi, kitu cha mtiririko lazima kiwe na maadili yaliyofafanuliwa ya vigezo.
Meneja wa usanidi lazima ahifadhi vigezo vyote vilivyotolewa na mtumiaji na maadili yaliyofafanuliwa (pamoja na maadili chaguo).
Vitu vya mtiririko katika mfumo wa usanidi vinapaswa kujumuisha:
`parameters`: Maadili yaliyofafanuliwa ya vigezo ambayo hutumiwa kwa mtiririko.
Darasa za msingi za processor zinahitaji kusaidia kubadilisha vigezo kupitia utaratibu uliopo wa ParametersSpec
Darasa la ParametersSpec (lililopo katika moduli sawa na ConsumerSpec na ProducerSpec) linapaswa kuimarishwa ikiwa ni lazima ili kusaidia kubadilisha kigezo
Wasindikaji wanapaswa kuwa na uwezo wa kuita ParametersSpec ili kusanidi vigezo vyao na maadili ya vigezo ambayo yamefafanuliwa wakati wa kuzindua mtiririko
Utaratibu wa utekelezaji wa ParametersSpec lazima:
Kukubali usanidi wa vigezo ambao una nafasi za vigezo (k.m., `{model}`, `{temperature}`)
Kusaidia kubadilisha vigezo wakati wa uendeshaji wa wasindikaji
Thibitisha kwamba maadili yaliyobadilishwa yanalingana na aina na vikwazo vilivyotarajiwa
Kutoa ushughulikiaji wa makosa kwa marejeleo yaliyopotea au yasiyo halali ya vigezo
#### Kanuni za Kubadilisha
Vigezo hutumia muundo wa `{parameter-name}` katika vigezo vya wasindikaji
Majina ya vigezo katika vigezo yanalingana na funguo katika sehemu ya `parameters` ya mtiririko
Kubadilisha hufanyika pamoja na `{id}` na `{class}`
Marejeleo yasiyo halali ya vigezo husababisha makosa wakati wa kuzindua
Uthibitisho wa aina hutokea kulingana na ufafanuzi wa vigezo uliohifadhiwa katikati
**MUHIMU**: Maadili yote ya vigezo huhifadhiwa na hutumwa kama maandishi
Nambari hubadilishwa kuwa maandishi (k.m., `0.7` inakuwa `"0.7"`)
Booleans hubadilishwa kuwa maandishi ya chini (k.m., `true` inakuwa `"true"`)
Hii inahitajika na schema ya Pulsar ambayo ina `parameters = Map(String())`
Darasa za msingi za processor zinahitaji kusaidia badiliko la vigezo kupitia utaratibu uliopo wa ParametersSpec.
Darasa la ParametersSpec (lililopo katika moduli sawa na ConsumerSpec na ProducerSpec) linapaswa kuimarishwa ikiwa ni lazima ili kusaidia badiliko la kiolezo la vigezo.
Wasindikaji wanapaswa kuwa na uwezo wa kutumia ParametersSpec ili kusanidi vigezo vyao na maadili ya vigezo ambayo yamefafanuliwa wakati wa kuzindua mtiririko.
Utaratibu wa utekelezaji wa ParametersSpec lazima:
Kukubali usanidi wa vigezo ambao una nafasi za vigezo (k.m., `{model}`, `{temperature}`).
Kusaidia badiliko la vigezo wakati wa utekelezaji wa processor.
Thibitisha kuwa maadili yaliyobadilishwa yanalingana na aina na vikwazo vilivyotarajiwa.
Kutoa usimamizi wa makosa kwa marejeleo yaliyopotea au yasiyo halali ya vigezo.
#### Kanuni za Badiliko
Vigezo hutumia muundo wa `{parameter-name}` katika vigezo vya processor.
Majina ya vigezo katika vigezo yanalingana na funguo katika sehemu ya `parameters` ya mtiririko.
Badiliko hufanyika pamoja na `{id}` na `{class}`.
Marejeleo yasiyo halali ya vigezo husababisha makosa wakati wa kuzindua.
Uthibitisho wa aina hutokea kulingana na ufafanuzi wa vigezo uliohifadhiwa katikati.
**MUHIMU**: Maadili yote ya vigezo huhifadhiwa na hutumwa kama maandishi.
Nambari hubadilishwa kuwa maandishi (k.m., `0.7` inakuwa `"0.7"`).
Maneno ya kweli hubadilishwa kuwa maandishi ya chini (k.m., `true` inakuwa `"true"`).
Hii inahitajika na schema ya Pulsar ambayo ina `parameters = Map(String())`.
