Kufungua kifaa cha Codex: jinsi tulivyounda Seva ya Programu

Wakala wa usimbaji wa OpenAI, Codex, anapatikana kwenye majukwaa mengi tofauti: programu ya wavuti⁠(fungua katika dirisha jipya), CLI⁠(fungua katika dirisha jipya), kiendelezi cha IDE⁠(fungua katika dirisha jipya), na programu mpya ya Codex ya macOS. Chini yake, zinaendeshwa zote na muunganisho uleule wa Codex—mchakato wa wakala na mantiki unaosimamia matumizi yote ya Codex. Kiungo muhimu kati yao ni kipi? Seva ya Programu ya Codex⁠(fungua katika dirisha jipya), API ya JSON-RPC¹ ya pande mbili, iliyo rahisi kwa kiteja.

Katika chapisho hili, tutatambulisha Seva ya Programu ya Codex; tutashiriki tulichojifunza hadi sasa kuhusu njia bora za kuleta uwezo wa Codex kwenye bidhaa yako ili kuwasaidia watumiaji wako kuboresha kwa kiwango kikubwa taratibu zao za kazi. Tutajadili usanifu na itifaki ya Seva ya Programu na jinsi inavyounganishwa na nyuso mbalimbali za Codex, pamoja na vidokezo vya kutumia Codex kwa ufanisi, iwe unataka kubadilisha Codex kuwa mkaguzi wa msimbo, wakala wa SRE, au msaidizi wa usimbaji.

Kabla ya kuingia katika usanifu, ni muhimu kujua historia ya Seva ya Programu. Hapo awali, Seva ya Programu ilikuwa njia halisi ya kutumia tena mfumo wa Codex katika bidhaa mbalimbali ambazo polepole zilibadilika na kuwa itifaki yetu ya kawaida.

Codex CLI ilianza kama TUI (kiolesura cha mtumiaji cha temino), ikimaanisha Codex inafikiwa kupitia temino. Tulipounda kiendelezi cha Msimbo wa VS (njia rahisi zaidi kwa IDE ya kuingiliana na mawakala wa Codex), tulihitaji njia ya kutumia kiunganishi kile kile ili kuendesha mchakato wa wakala ule ule kutoka kwenye UI ya IDE bila kuutekeleza upya. Hiyo ilimaanisha kuunga mkono mifumo tajiri ya miingiliano zaidi ya ombi/majibu, kama vile kuchunguza eneokazi, kutiririsha maendeleo kadri wakala anavyowaza, na kutoa mabadiliko. Kwanza tulijaribu kufichua Codex kama seva ya MCP⁠(fungua katika dirisha jipya), lakini kudumisha semantiki za MCP kwa njia iliyoleta maana kwa Msimbo wa VS ilithibitika kuwa ngumu. Badala yake, tulianzisha itifaki ya JSON-RPC iliyofanana na mzunguko wa TUI, ambayo ikawa toleo la kwanza lisilo rasmi⁠(fungua katika dirisha jipya) la Seva ya Programu. Wakati huo, hatukutarajia viteja vingine kutegemea Seva ya Programu, kwa hivyo haikubuniwa kama API imara.

Kadiri upokeaji wa Codex ulivyoongezeka katika miezi michache iliyofuata, timu za ndani na washirika wa nje walitaka uwezo wa kujumuisha kiunganishi kile kile katika bidhaa zao wenyewe ili kuharakisha taratibu za kazi za maendeleo ya programu kwa watumiaji wao. Kwa mfano, JetBrains na Xcode zilitaka uzoefu wa wakala wa kiwango cha IDE, wakati programu ya mezani ya Codex ilihitaji kuratibu mawakala wengi wa Codex kwa wakati mmoja. Mahitaji hayo yalitusukuma kubuni uso wa jukwaa ambao bidhaa zetu na ujumuishaji wa washirika unaweza kutegemea kwa usalama kwa muda mrefu. Ilihitaji kuwa rahisi kuunganisha na kuwa na utangamano wa kurudisha nyuma, ikimaanisha kwamba tunaweza kubadilisha itifaki bila kuharibu viteja vya sasa.

Ifuatayo, tutapitia jinsi tulivyounda usanifu na itifaki ili viteja tofauti viweze kutumia kiunganishi kilekile.

Kwanza, hebu tuangalie kwa undani kilicho ndani ya kiiunganishi cha Codex na jinsi Seva ya Programu ya Codex inavyokionyesha kwa viteja. Katika blogu yetu ya mwisho ya Codex, tulichambua mchakato wa msingi wa wakala unaoratibu mwingiliano kati ya mtumiaji, muundo, na zana. Hii ndiyo mantiki ya msingi ya mfumo wa Codex, lakini kuna zaidi katika uzoefu kamili wa wakala:

1. Mzunguko wa maisha wa msururu na uthabiti. Msururu ni mazungumzo ya Codex kati ya mtumiaji na wakala. Codex huunda, huendeleza, hunakili, na kuhifadhi misururu, na hudumisha historia ya matukio ili viteja viweze kuunganisha tena na kuonyesha ratiba thabiti.

2. Usanidi na uthibitisho. Codex hupakia usanidi, husimamia chaguomsingi, na huendesha mitiririko ya uthibitishaji kama “Ingia kwa kutumia ChatGPT,” ikijumuisha hali ya vitambulisho.

3. Utekelezaji na viendelezi vya zana. Codex hutekeleza zana za sheli/faili katika sehemu ya majaribio na huunganisha miunganisho kama seva za MCP na ujuzi ili ziweze kushiriki katika mchakato wa wakala chini ya muundo thabiti wa sera.

Mantiki yote ya wakala tuliyotaja hapa, ikijumuisha mchakato wa msingi wa wakala, iko katika sehemu ya msimbo wa Codex CLI inayoitwa “Codex core⁠(fungua katika dirisha jipya).” Codex core ni maktaba ambapo msimbo wote wa wakala unapatikana na pia ni mazingira ya utekelezaji yanayoweza kuwashwa ili kuendesha mchakato wa wakala na kudhibiti uhifadhi wa kudumu wa msururu mmoja wa Codex (mazungumzo).

Ili kuwa na manufaa, kiunganishi cha Codex kinahitaji kupatikana kwa viteja. Hapo ndipo Seva ya Programu inapoingia.

Seva ya Programu ni itifaki ya JSON-RPC kati ya kiteja na seva na pia ni mchakato wa muda mrefu unaoendesha misururu ya Codex core. Kama tunavyoweza kuona kutoka kwenye mchoro ulio hapo juu, mchakato wa Seva ya Programu una vipengele vinne vikuu: kisomaji cha stdio, kichakataji cha ujumbe cha Codex, kidhibiti cha misururu, na misururu ya msingi. Kisimamizi cha misururu huanzisha kikao kimoja cha msingi kwa kila msururu, na kichakataji cha ujumbe cha Codex huwasiliana moja kwa moja na kila kikao cha msingi ili kuwasilisha maombi ya kiteja na kupokea masasisho.

Ombi moja la kiteja linaweza kusababisha masasisho mengi ya matukio, na matukio haya ya kina ndiyo yanayotuwezesha kuunda UI tajiri juu ya Sea ya Programu. Zaidi ya hayo, kisomaji cha stdio na kichakataji cha ujumbe cha Codex hutumika kama safu ya tafsiri kati ya kiteja na misururu ya Codex core. Zinatafsiri maombi ya JSON-RPC ya kiteja kuwa shughuli za Codex core, husikiliza mtiririko wa matukio ya ndani ya Codex, na kisha hubadilisha matukio hayo ya kiwango cha chini kuwa seti ndogo ya arifa thabiti za JSON-RPC zilizo tayari kwa UI.

Itifaki ya JSON-RPC kati ya kiteja na Seva ya Programu ni ya pande zote kikamilifu. Msururu wa kawaida una ombi la kiteja na arifa nyingi za seva. Zaidi ya hayo, seva inaweza kuanzisha maombi wakati wakala anahitaji ingizo, kama vile idhini, kisha kusitisha kitengo cha msingi hadi kiteja kitakapojibu.

Ifuatayo, tutachambua vitengo vidogo zaidi vya mazungumzo, vijenzi vya msingi vya itifaki ya Seva ya Programu. Kubuni API kwa ajili ya mchakato wa wakala ni changamoto kwa sababu mwingiliano kati ya mtumiaji na wakala si ombi/jibu rahisi. Ombi moja la mtumiaji linaweza kujitokeza na kuwa mfuatano uliopangwa wa vitendo ambavyo kiteja kinahitaji kuwakilisha kwa uaminifu: ingizo la mtumiaji, maendeleo ya hatua kwa hatua ya wakala, na mabaki yanayozalishwa njiani (mfano, mabadiliko). Ili kufanya mtiririko huo wa mwingiliano uwe rahisi kuujumuisha na uwe thabiti katika UIs, tuliamua kutumia vitengo vitatu vidogo zaidi vya msingi vyenye mipaka na mizunguko ya maisha iliyo wazi:

1. Kipengee: Kipengee ni kitengo cha msingi cha ingizo/matokeo katika Codex. Vipengee vinaainishwa kwa aina (k.m., ujumbe wa mtumiaji, ujumbe wa wakala, utekelezaji wa zana, ombi la idhini, mabadiliko) na kila kimoja kina mzunguko wa maisha ulioainishwa wazi:

• item/started wakati kipengee kinapoanza
• matukio ya hiari ya item/*/delta maudhui yakitiririka (kwa aina za vipengee vya kutiririsha)
• item/completed wakati kipengee kinapomalizana na kiinadata chake cha temino

Mzunguko huu wa maisha unaviruhusu viteja kuanza kutoa taswira mara moja kwenye started, tiririsha masasisho ya hatua kwa hatua kwenye delta, na kamilisha kwenye completed.

2. Kitengo cha msingi: Kitengo cha msingi ni kitengo kimoja cha kazi ya wakala kinachoanzishwa na ingizo la mtumiaji. Huanza wakati kiteja kinapowasilisha ingizo (kwa mfano, “endesha majaribio na ufupishe hitilafu”) na huisha wakati wakala anapomaliza kutoa matokeo kwa ingizo hilo. Kitengo cha msingi kina mfuatano wa vipengele vinavyowakilisha hatua za kati na matokeo yanayozalishwa njiani.

3. Msururu: Msururu ni mazingira thabiti kwa ajili ya kipindi kinachoendelea cha Codex kati ya mtumiaji na wakala. Yana vitengo vingi vya msingi Misururu inaweza kuundwa, kuendelezwa, kugawanywa, na kuhifadhiwa. Historia ya misururu huhifadhiwa ili viteja viweze kuunganishwa tena na kuonyesha ratiba iliyo thabiti.

Sasa, tutaangalia mazungumzo rahisi kati ya kiteja na wakala, ambapo mazungumzo yanawakilishwa na vitengo vidogo zaidi:

Mwanzoni mwa mazungumzo, kiteja na seva zinahitaji kuanzisha muunganisho salama. Kiteja lazima kitume ombi moja la muunganisho kabla ya mbinu nyingine yoyote, na seva ithibitishe kwa kutoa jibu. Hii inatoa seva fursa ya kutangaza uwezo na inaruhusu pande zote mbili kukubaliana kuhusu upangaji wa matoleo ya itifaki, vibadilisha vipengele, na chaguo-msingi kabla ya kazi halisi kuanza. Huu hapa ni mfano wa kiinidata kutoka kwenye kiendelezi cha Msimbo wa VS Code wa OpenAI:

Hivi ndivyo seva inavyorejesha:

Kiteja kinapowasilisha ombi jipya, kwanza kitaunda msururu kisha kitengo cha msingi. Seva itatuma arifa za maendeleo (thread/started na turn/started). Pia itarudisha viingizo inavyovisajili kama vipengee, kama vile ujumbe wa mtumiaji hapa.

Miingiliano ya zana pia hutumwa kwa kiteja kama vipengee. Zaidi ya hayo, seva inaweza kuomba idhini ya mteja kabla ya kuweza kutekeleza kitendo kwa kutuma ombi la seva. Uidhinishaji utasitisha kitengo cha msingi hadi kiteja kitakapojibu kwa “ruhusu” au “kataza.” Hivi ndivyo mtiririko wa uidhinishaji unavyoonekana katika kiendelezi cha Msimbo wa VS:

Mwishowe, seva hutuma ujumbe wa wakala na kisha kutamatisha kitengo cha msingi kwa turn/completed. Matukio ya delta ya ujumbe wa wakala hutiririsha vipande vya ujumbe hadi ujumbe ukamilishwe na turn/completed.

Ujumbe katika mchoro umerahisishwa ili kuwezesha usomaji. Ikiwa ungependa kuona JSON ya mzunguko kamili, unaweza kuendesha kiteja cha majaribio kutoka kwenye hifadhi ya Codex CLI:

Sasa, hebu tuangalie jinsi nyuso tofauti za viteja zinavyojumuisha Codex kupitia Seva ya Programu. Tutashughulikia mifumo mitatu: programu za ndani na IDEs, muda wa kutekeleza wavuti ya Codex, na TUI.

Katika zote tatu, usafirishaji ni JSON-RPC kupitia stdio (JSONL). JSON-RPC hurahisisha kuunda vifungo vya kiteja katika lugha unayochagua. Sehemu za Codex na miunganisho ya washirika zimetekeleza viteja vya Seva ya Programu katika lugha zikiwemo Go, Python, TypeScript, Swift, na Kotlin. Kwa TypeScript, unaweza kuzalisha ufafanuzi moja kwa moja kutoka kwenye itifaki ya Rust kwa kuendesha:

Kwa lugha nyingine, unaweza kuzalisha kifurushi cha kielezo cha JSON na kukiingiza kwenye kizalisha misimbo unachokipendelea kwa kuendesha:

Viteja vya ndani kwa kawaida huunganisha au kuleta mfumo wa jukwaa maalum la Seva ya Programu, hivyo kuizindua kama mchakato wa muda mrefu wa kitoto, na kuweka njia wazi ya pande mbili ya stdio JSON-RPC. Katika kiendelezi chetu cha Msimbo wa VS na Programu ya Eneo-kazi, kwa mfano, kifurushi kilichosafirishwa kinajumuisha mfumo wa jukwaa maalum la Codex na kimefungwa kwenye toleo lililojaribiwa ili kiteja kiendeshe kila wakati biti halisi tulizothibitisha.

Sio kila ujumuishaji unaweza kusafirisha masasisho ya kiteja mara kwa mara. Baadhi ya washirika kama Xcode hutenganisha mizunguko ya matoleo kwa kuweka kiteja thabiti na kuruhusu kuelekeza kwenye mfumo mpya zaidi wa Seva ya Programu inapohitajika. Kwa njia hiyo wanaweza kupitisha maboresho ya upande wa seva (kwa mfano, ujumuishaji bora wa kiotomatiki katika Codex core au funguo za usanidi zilizoungwa mkono hivi karibuni) na kusambaza marekebisho ya hitilafu bila kusubiri toleo la kiteja. Uso wa JSON-RPC wa Seva ya Programu umeundwa ili kuwa na uoanifu wa kurudi nyuma, hivyo viteja vya zamani vinaweza kuzungumza na seva mpya kwa usalama.

Wavuti wa Codex hutumia kiunganishi cha Codex, lakini huiendesha katika mazingira ya kontena. Mfanyakazi huandaa mazingira na eneokazi iliyokaguliwa, huanzisha mfumo wa Seva ya Programu ndani yake, na hudumisha JSON-RPC ya muda mrefu kupitia njia ya stdio². Programu ya wavuti (inayoendeshwa kwenye kichupo cha kivinjari cha mtumiaji) huwasiliana na sehemu ya nyuma ya Codex kupitia HTTP na SSE, ambayo hutiririsha matukio ya kazi yanayozalishwa na mfanyakazi. Hii huifanya UI ya upande wa kivinjari kuwa nyepesi huku bado ikitupatia muda thabiti wa kutekeleza kwenye eneokazi na wavuti.

Kwa sababu vipindi vya wavuti ni vya muda mfupi (vichupo hufungwa, mitandao hukatika), programu ya wavuti haiwezi kuwa chanzo cha ukweli kwa kazi zinazochukua muda mrefu. Kuhifadhi hali na maendeleo kwenye seva kunamaanisha kazi inaendelea hata kama kichupo kitatoweka. Itifaki ya utiririshaji na vikao vya msururu vilivyohifadhiwa hufanya iwe rahisi kwa kikao kipya kuunganisha tena, kuendelea pale kilipoachia, na kufuatilia bila kujenga upya hali kwenye kiteja.

Kihistoria, TUI ilikuwa kiteja “asili” kilichofanya kazi katika mchakato uleule kama mchakato wa wakala na kuzungumza moja kwa moja na aina za msingi za Rust badala ya itifaki ya seva ya programu. Hilo lilifanya mizunguko ya awali kuwa ya haraka, lakini pia lilifanya TUI kuwa sehemu ya hali maalum.

Sasa kwa kuwa Seva ya Programu ipo, tunapanga kufanya upya muundo wa TUI⁠(fungua katika dirisha jipya) ili kuitumia ili itende kama kiteja kingine chochote: kuzindua mchakato wa kitoto cha Seva ya Programu, kuzungumza na JSON-RPC kupitia stdio, na kuonyesha matukio na idhini zilezile za utiririshaji. Hii inafungua taratibu za kazi ambapo TUI inaweza kuunganisha na seva ya Codex inayoendeshwa kwenye mashine ya mbali, ikimuweka wakala karibu na rasilimali za kompyuta na kuendelea na kazi hata kama kipakatalishi kitaingia usingizini au kitakatisha muunganisho, huku bado kikitoa masasisho ya moja kwa moja na vidhibiti vya ndani.

Seva ya Programu ya Codex itakuwa mbinu ya ujumuishaji ya kiwango cha juu tutakayoendelea kuitunza kuanzia sasa, lakini pia kuna mbinu nyingine zenye utendaji mdogo zaidi. Kwa chaguo-msingi, tunapendekeza viteja vitumie Seva ya Programu ya kuunganisha na Codex, lakini inafaa kuangalia mbinu tofauti za uunganishaji na kuelewa faida na hasara zake. Zifuatazo ni njia za kawaida zaidi za kutumia Codex na wakati ambapo kila moja inaweza kuwa chaguo bora.

Endesha codex mcp-server⁠(fungua katika dirisha jipya) na uunganishe kutoka kwenye kiteja chochote cha MCP kinachokubali seva za stdio (mfano, OpenAI Agents SDK⁠(fungua katika dirisha jipya)). Hii inafaa ikiwa tayari una utaratibu wa kazi unaotegemea MCP na unataka kuanzisha Codex kama zana inayoweza kuingiliana. Ubaya ni kwamba unapata tu kile ambacho MCP hufichua, kwa hivyo mwingiliano mahususi wa Codex unaotegemea semantiki tajiri za kipindi (mfano, masasisho ya mabadiiko) huenda usilingane kwa urahisi kupitia sehemu za mwisho za MCP.

Baadhi ya mifumo ya ikolojia hutoa kiolesura cha kubebeka kinachoweza kulenga watoa huduma wengi wa miundo na mazingira ya utekelezaji. Hii inaweza kuwa chaguo nzuri ikiwa unataka dhana moja inayoratibu mawakala wengi. Mbadilishano ni kwamba itifaki hizi mara nyingi huungana kwenye sehemu ya kawaida ya uwezo, jambo linaloweza kufanya miingiliano anuwai kuwa migumu kuwakilisha, hasa wakati semantiki za zana na kikao maalum kwa mtoa huduma zinapokuwa muhimu. Eneo hili linabadilika kwa haraka, na tunatarajia kwamba viwango vya kawaida zaidi vitaibuka tunapobaini vitengo vidogo bora zaidi vya kuwakilisha taratibu za kazi za mawakala wa ulimwengu halisi (ujuzi⁠(fungua katika dirisha jipya) ni mfano mzuri wa hili).

Chagua Seva ya Programu unapohitaji kiunganishi kamili cha Codex kifichuliwe kama mtiririko thabiti wa matukio unaofaa kwa UI. Unapata utendaji kamili wa mchakato wa wakala na vipengele vingine vya usaidizi kama vile Ingia ukitumia ChatGPT, ugunduzi wa miundo, na usimamizi wa usanidi. Gharama kuu ni kazi ya ujumuishaji, kwa kuwa unahitaji kuunda JSON-RPC inayofunga upande wa kiteja kwa lugha yako. Hata hivyo, kihalisia Codex ina uwezo wa kufanya kazi nyingi nzito ikiwa utaiwekea kielezo cha JSON na nyaraka. Timu nyingi tulizoshirikiana nazo ziliweza kufanikisha ujumuishaji unaofanya kazi haraka kwa kutumia Codex.

Hali nyepesi ya CLI inayoweza kuandikwa kwa hati kwa kazi za mara moja na uendeshaji wa CI. Inafaa kwa uwekaji otomatiki na mikondo ambapo unataka amri moja iendeshwe hadi ikamilike bila mwingiliano, itiririshe matokeo yaliyopangwa kwa kumbukumbu, na itoke ikiwa na ishara wazi ya mafanikio au kushindwa.

Maktaba ya TypeScript ya kudhibiti mawakala wa ndani wa Codex kwa njia ya programu kutoka ndani ya programu yako mwenyewe. Ni bora zaidi unapohitaji kiolesura asilia cha maktaba kwa ajili ya zana za upande wa seva na taratibu za kazi bila kuunda kiteja tofauti wa JSON-RPC. Kwa kuwa ilisafirishwa mapema kuliko Seva ya Programu, kwa sasa inaunga mkono lugha chache na eneo dogo la matumizi. Ikiwa wasanidi programu wana nia, tunaweza kuongeza SDK za ziada zinazofunika itifaki ya Seva ya Progrramu App ili timu ziweze kufunika zaidi ya sehemu ya kiunganishi bila kuandika vifungo vya JSON-RPC.

Katika chapisho hili, tulishiriki jinsi tunavyokaribia kubuni kiwango kipya cha miingiliano na mawakala na jinsi ya kugeuza Codex kuwa itifaki thabiti, na rahisi kwa kiteja. Tulizungumzia jinsi Seva ya Programu inavyofichua Codex core, inavyowawezesha viteja kuendesha mchakato kamili wa wakala, na inavyowezesha anuwai ya sehemu ikijumuisha TUI, miunganisho ya IDE ya ndani, na mazingira ya uendeshaji wa wavuti.

Ikiwa hii ilikupa mawazo ya kuunganisha Codex kwenye taratibu zako za kazi, ni muhimu kujaribu Seva ya Programu. Msimbo wote wa chanzo unapatikana katika hifadhi ya chanzo huria ya hifadhi⁠(fungua katika dirisha jipya) ya Codex CLI. Tafadhali jisikie huru kushiriki maoni yako na maombi ya vipengele. Tunafurahi kusikia kutoka kwako na kuendelea kufanya mawakala wapatikane kwa urahisi zaidi kwa kila mtu.