Að afhjúpa Codex-fulltrúalykkjuna

Codex CLI⁠(opnast í nýjum glugga) er fjölverkvangs staðbundinn hugbúnaðarfulltrúi okkar, hannaður til að skila hágæða og áreiðanlegum hugbúnaðarbreytingum á meðan hann starfar á öruggan og skilvirkan hátt á tölvunni þinni. Við höfum lært gríðarlega mikið um hvernig á að byggja heimsklassa hugbúnaðarfulltrúa frá því að við settum CLI fyrst á markað í apríl⁠. Til að greina þessar innsýnir nánar er þetta fyrsta færsla í áframhaldandi greinaflokki þar sem við munum kanna ýmsa þætti þess hvernig Codex virkar, sem og lærdóma sem hafa kostað sitt. (Fyrir enn ítarlegri sýn á hvernig Codex CLI er byggt, skoðaðu opna geymslu okkar á https://github.com/openai/codex⁠(opnast í nýjum glugga). Mörg af fínni smáatriðum hönnunarákvarðana okkar eru skráð í GitHub-verkefnum og draga beiðnum ef þú vilt fræðast meira.)

Til að byrja með munum við einbeita okkur að fulltrúalykkjunni, sem er kjarnalógíkin í Codex CLI sem ber ábyrgð á að samræma samskiptin milli notandans, líkansins og verkfæranna sem líkanið kallar á til að framkvæma merkingarbæra hugbúnaðarvinnu. Við vonum að þessi færsla gefi þér góða innsýn í hlutverk fulltrúa okkar (eða „umhverfi“) í að nýta LLM.

Áður en við byrjum er hér stutt athugasemd um hugtakanotkun: hjá OpenAI nær „Codex“ yfir safn hugbúnaðarfulltrúa, þar á meðal Codex CLI, Codex Cloud og Codex VS Code-viðbótina. Þessi færsla fjallar um Codex umhverfi, sem veitir kjarna fulltrúalykkjuna og keyrslurökfræðina sem liggja að baki allri Codex-upplifun og eru gerðar aðgengilegar í gegnum Codex CLI. Til einföldunar hér munum við nota hugtökin „Codex“ og „Codex CLI“ jöfnum höndum.

Í hjarta hvers gervigreindarfulltrúa er eitthvað sem kallast „fulltrúalykkjan.“ Einföld myndræn framsetning á fulltrúalykkjunni lítur svona út:

Til að byrja tekur fulltrúinn inntak frá notandanum til að hafa með í safni textaleiðbeininga sem hann undirbýr fyrir líkanið sem kallast kvaðning.

Næsta skref er að spyrja líkanið með því að senda því leiðbeiningarnar okkar og biðja það um að búa til svar, ferli sem kallast ályktun. Við ályktun er textakvaðningin fyrst þýdd yfir í runu af inntaks tákna⁠(opnast í nýjum glugga)—heiltölum sem vísa inn í orðaforða líkansins. Þessi tákn eru síðan notuð til að keyra líkanið, sem framleiðir nýja röð af úttakstáknum.

Úttaksttákn eru þýddiaftur í texta, sem verður svar líkansins. Þar sem tákn eru framleidd í áföngum getur þessi þýðing átt sér stað á meðan líkanið keyrir, sem er ástæðan fyrir því að mörg forrit byggð á LLM sýna úttak í rauntíma. Í reynd er ályktun venjulega falin á bak við API sem vinnur með texta og felur þannig smáatriði um tókavæðingu.

Sem niðurstaða ályktunarskrefsins annaðhvort (1) gefur líkanið endanlegt svar við upprunalegu inntaki notandans, eða (2) biður um verkfærakall sem gert er ráð fyrir að fulltrúinn framkvæmi (t.d. „keyra ls og skila niðurstöðunni“). Í tilviki (2) framkvæmir fulltrúinn verkfærakallið og bætir úttaki þess við upprunalegu kvaðninguna. Þetta úttak er notað til að búa til nýtt inntak sem er notað til að endurkeyra fyrirspurn á líkanið; fulltrúinn getur þá tekið þessar nýju upplýsingar með í reikninginn og reynt aftur.

Þetta ferli endurtekur sig þar til líkanið hættir að senda út verkfæraköll og í staðinn sendir skilaboð til notandans (kallað aðstoðarskilaboð í OpenAI-líkönum). Í mörgum tilvikum svara þessi skilaboð beint upprunalegri beiðni notandans, en þau geta einnig verið eftirfylgnispurning til hans.

Þar sem fulltrúinn getur framkvæmt verkfæraköll sem breyta staðbundnu umhverfi, er úttak hans ekki takmarkað við skilaboð aðstoðarmannsins. Í mörgum tilvikum er aðalúttak hugbúnaðarfulltrúa kóðinn sem hann skrifar eða breytir á tölvunni þinni. Engu að síður endar hver umferð alltaf með skilaboðum frá aðstoðarmanni—til dæmis „Ég bætti við architecture.md sem þú baðst um“—sem gefur til kynna lokastöðu í fulltrúalykkjunni. Frá sjónarhóli fulltrúans er verki hans lokið og stjórn færist aftur til notandans.

Ferðalagið frá inntaki notanda til svars fulltrúa sem sýnt er á skýringarmyndinni er kallað einn snúningur í samtali (þráður í Codex). Þó að þessi samtalsumferð geti falið í sér margar ítranir á milli líkanálits og verkfærakalla. Í hvert skipti sem þú sendir ný skilaboð í núverandi samtal, er samtalsferillinn innifalinn sem hluti af kvaðningunni fyrir nýja umferð, sem inniheldur skilaboðin og verkfæraköllin úr fyrri umferðum:

Þetta þýðir að eftir því sem samtalið vex, lengist einnig kvaðningin sem notuð er til að taka úrtak á líkaninu. Þessi lengd skiptir máli vegna þess að hvert líkan hefur samhengisglugga, sem er hámarksfjöldi tákna sem það getur notað í einu ályktunarkalli. Athugaðu að þessi gluggi inniheldur bæði inntaks og úttakstákn. Eins og þú gætir ímyndað þér, gæti fulltrúi ákveðið að framkvæma hundruð verkfærakalla í einni umferð, sem gæti hugsanlega tæmt samhengisgluggann. Af þessum sökum er stjórnun samhengisglugga ein af mörgum skyldum fulltrúans. Nú skulum við kafa ofan í hvernig Codex keyrir fulltrúalykkjuna.

Codex CLI sendir HTTP-beiðnir til Responses API⁠(opnast í nýjum glugga) til að framkvæma líkanályktun. Við munum skoða hvernig upplýsingar flæða í gegnum Codex, sem notar Responses API til að knýja fulltrúalykkjuna.

Endapunkturinn fyrir Responses API sem Codex CLI notar er hægt að stilla⁠(opnast í nýjum glugga), svo hægt er að nota hann með hvaða endapunkti sem styður Responses API⁠(opnast í nýjum glugga):

• Þegar þú skráir þig inn með ChatGPT⁠(opnast í nýjum glugga) í Codex CLI, notar það https://chatgpt.com/backend-api/codex/responses sem endapunkt
• Þegar þú notar API-lykilsauðkenningu⁠(opnast í nýjum glugga) með líkönum sem eru hýst á OpenAI-verkvangi, notarðu https://api.openai.com/v1/responses sem endapunkt
• Þegar þú keyrir Codex CLI með --oss til að nota gpt-oss⁠ með ollama 0.13.4+⁠(opnast í nýjum glugga) eða LM Studio 0.3.39+⁠(opnast í nýjum glugga), þá er sjálfgefið að http://localhost:11434/v1/responses keyri staðbundið á tölvunni þinni
• Codex CLI er hægt að nota með Responses API sem er hýst af skýjaveitu eins og Azure.

Skoðum hvernig Codex býr til kvaðninguna fyrir fyrsta ályktunarkallið í samtali.

Sem endanlegur otandi tilgreinir þú ekki kvaðninguna sem notuð er til að sýna líkanið orðrétt þegar þú sendir fyrirspurn til Responses API. Í staðinn tilgreinir þú ýmsar inntakstegundir sem hluta af fyrirspurninni þinni, og Responses API-þjónninn ákveður hvernig eigi að setja þessar upplýsingar fram í kvaðningu sem líkanið er hannað til að vinna úr. Þú getur hugsað um kvaðninguna sem „lista yfir atriði“; þessi kafli útskýrir hvernig fyrirspurnin þín er breytt í þann lista.

Í upphaflegu kvaðningunni er hvert atriði á listanum tengt við hlutverk. role gefur til kynna hversu mikið vægi tengt efni á að hafa og er eitt af eftirfarandi gildum (í minnkandi forgangsröð): system, developer, user, assistant.

Responses API⁠(opnast í nýjum glugga) tekur við JSON-farmi með mörgum breytum. Við munum einbeita okkur að þessum þremur atriðum:

• instructions⁠(opnast í nýjum glugga): kerfisskilaboð (eða skilaboð frá forritara) sett inn í samhengi líkansins
• tools⁠(opnast í nýjum glugga): listi yfir verkfæri sem líkanið gæti kallað á meðan það býr til svar
• input⁠(opnast í nýjum glugga): listi af texta-, mynda- eða skráarinntökum fyrir líkanið

Í Codex er instructions reiturinn lesinn úr model_instructions_file⁠(opnast í nýjum glugga) í ~/.codex/config.toml, ef það er tilgreint; annars eru base_instructions sem tengjast líkani⁠(opnast í nýjum glugga) sem notað er. Líkansértækar leiðbeiningar eru í Codex repo og eru settar saman í CLI (t.d. gpt-5.2-codex_prompt.md⁠(opnast í nýjum glugga)).

Reiturinn tools er listi yfir verkfæraskilgreiningar sem samræmast skema sem er skilgreint af Responses API. Fyrir Codex felur þetta í sér verkfæri sem eru veitt af Codex CLI, verkfæri sem eru veitt af Responses API sem ættu að vera gerð aðgengileg Codex, sem og verkfæri sem notandinn veitir, yfirleitt í gegnum MCP netþjóna:

Að lokum er input reiturinn í JSON-farminum listi yfir atriði. Codex setur inn eftirfarandi atriði⁠(opnast í nýjum glugga) í input áður en bætt er við notandaskilaboðinu:

1 Skilaboð með role=developer sem lýsa sandkassanum sem á aðeins við um Codex-útvegaða shell verkfærið sem er skilgreint í tools hlutanum. Það er að segja, önnur verkfæri, eins og þau sem eru veitt af MCP-netþjónum, eru ekki í sandkassa af Codex og bera ábyrgð á að framfylgja eigin öryggisráðstöfunum.

Skilaboðin eru byggð á sniðmáti þar sem lykilhlutar efnisins koma úr Markdown-bútum sem fylgja með Codex CLI, eins og workspace_write.md⁠(opnast í nýjum glugga) og on_request.md⁠(opnast í nýjum glugga):

2. (Valfrjálst) Skilaboð með role=developer þar sem innihaldið er gildið developer_instructions sem lesið er úr config.toml skrá notandans.

3. (Valfrjálst) Skilaboð með role=user þar sem innihaldið eru „leiðbeiningar notanda“, sem eru ekki sóttar úr einni skrá heldur er safnað saman úr mörgum heimildum⁠(opnast í nýjum glugga). Almennt koma sértækari leiðbeiningar fram síðar:

• Innihald AGENTS.override.md og AGENTS.md í $CODEX_HOME
• Háð takmörkum (32 KiB, sjálfgefið), leitaðu í hverri möppu frá Git/verkefnarót cwd (ef hún er til) upp að cwd sjálfu: bættu við innihaldi hvers AGENTS.override.md, AGENTS.md, eða hvaða skráarheiti sem er tilgreint í project_doc_fallback_filenames í config.toml
• Ef einhverjir skills⁠(opnast í nýjum glugga) hafa verið stilltir:
  • stuttur inngangur um hæfni
  • skill metadata⁠(opnast í nýjum glugga) fyrir hverja færni
  • hluti um hvernig á að nota færni⁠(opnast í nýjum glugga)

4. Skilaboð með role=user sem lýsa staðbundnu umhverfi þar sem fulltrúinn starfar núna. Þetta tilgreinir núverandi vinnuskráarslóð og skel notandans⁠(opnast í nýjum glugga):

Þegar Codex hefur lokið öllum ofangreindum útreikningum til að upphafsstilla input, bætir það notandaskilaboðinu við til að hefja samtalið.

Fyrri dæmin lögðu áherslu á innihald hvers skilaboðs, en athugaðu að hver þáttur í input er JSON-hlutur með type, role⁠(opnast í nýjum glugga) og content eins og hér segir:

Þegar Codex hefur búið til fullan JSON-farm til að senda til Responses API, framkvæmir það HTTP POST beiðni með Authorization haus, allt eftir því hvernig Responses API endapunkturinn er stilltur í ~/.codex/config.toml (viðbótar HTTP-hausar og fyrirspurnarbreytur eru bættar við ef það er tilgreint).

Þegar OpenAI Responses API þjónninn fær beiðnina notar hann JSON til að búa til kvaðningu fyrir líkanið á eftirfarandi hátt (til öryggis gæti sérsniðin útfærsla á Responses API valið aðra leið):

Eins og þú sérð er röð fyrstu þriggja atriðanna í kvaðningunni ákvörðuð af þjóninum, ekki af biðlaranum. Að því sögðu, af þessum þremur atriðum er aðeins efni kerfisskilaboðanna einnig stjórnað af þjóninum, þar sem verkfæri og leiðbeiningar eru ákvörðuð af biðlaranum. Þessu er fylgt eftir með input úr JSON-farminum til að ljúka kvaðningunni.

Nú þegar við höfum kvaðninguna okkar, erum við tilbúin að taka dæmi úr líkaninu.

Þessi HTTP-beiðni til Responses API hefur fyrstu „umferð“ samtals í Codex. Netþjónninn svarar með straumi af atburðum sendum frá netþjóni (SSE⁠(opnast í nýjum glugga)). data hvers atburðar er JSON-farmur með "type" sem byrjar á "response", sem gæti verið eitthvað á borð við þetta (heildarlisti yfir atburði er að finna í API-skjölum⁠(opnast í nýjum glugga)):

Codex tekur við viðburðastraumi⁠(opnast í nýjum glugga) og birtir þá aftur sem innri viðburðahluti sem viðskiptavinur getur notað. Atburðir eins og response.output_text.delta eru notaðir til að styðja við streymi í notendaviðmótinu, á meðan aðrir atburðir eins og response.output_item.added eru umbreyttir í hluti sem eru bættir við input fyrir næstu köll Responses API.

Gerum ráð fyrir að fyrsta beiðnin til Responses API innihaldi tvö response.output_item.done atvik: eitt með type=reasoning og eitt með type=function_call. Þessir atburðir verða að vera tilgreindir í input reitnum í JSON þegar við spyrjum líkanið aftur með svarinu við verkfærakallinu. 

Niðurstaðan af kvaðningunni sem notuð er til að taka sýni úr líkaninu í síðari fyrirspurn myndi líta svona út:

Sérstaklega skaltu taka eftir því hvernig gamla kvaðningin er nákvæmlega forskeyti nýju kvaðningarinnar. Þetta er viljandi, þar sem þetta gerir síðari beiðnir mun skilvirkari vegna þess að það gerir okkur kleift að nýta kvaðningarskyndiminni (sem við munum ræða í næsta kafla um afköst).

Þegar við lítum til baka á fyrstu skýringarmyndina af fulltrúalykkjunni sjáum við að það gætu verið margar ítranir á milli ályktunar og verkfærakalla. Kvaðningin gæti haldið áfram að vaxa þar til við fáum loks skilaboð frá aðstoðarmanni, sem gefur til kynna að umferðinni sé lokið:

Í Codex CLI birtum við aðstoðarmannsskilaboðin fyrir notandann og beinum athyglinni að ritlinum til að gefa notandanum til kynna að nú sé komið að þeim að halda samtalinu áfram. Ef notandinn svarar, þarf bæði að bæta skilaboðum aðstoðarmannsins frá fyrri umferð og nýjum skilaboðum notandans við input í Responses API-beiðninni til að hefja nýja umferð:

Aftur, þar sem við höldum áfram samtalinu, eykst lengd input sem við sendum til Responses API stöðugt:

Skoðum hvað þessi sífellt vaxandi kvaðning þýðir fyrir frammistöðu.

Þú gætir verið að spyrja sjálfa(n) þig: „Bíddu, er fulltrúalykkjan ekki ferningstengd miðað við magn JSON sem er sent til Responses API yfir gang samtalsins?“ Og þú hefur rétt fyrir þér. Þó að Responses API styðji valfrjálsa previous_response_id⁠(opnast í nýjum glugga) færibreytu til að draga úr þessu vandamáli, notar Codex hana ekki í dag, fyrst og fremst til að halda beiðnum algjörlega ástandslausum og til að styðja við stillingar fyrir engin gögn varðveitt (ZDR).

Almennt er kostnaðurinn við að taka sýni úr líkaninu meiri en kostnaðurinn við netumferð, sem gerir sýnatöku að aðalmarkmiði skilvirknivinnu okkar. Þess vegna er skyndiminni fyrir kvaðningar svo mikilvægt, þar sem það gerir okkur kleift að endurnýta útreikninga úr fyrra ályktunarkalli. Þegar við fáum skyndiminnisfund, er úrtaka úr líkaninu línuleg frekar en veldisvísisleg. Skjöl okkar um skyndiminnikvaðningu ⁠(opnast í nýjum glugga)útskýrir þetta nánar:

Skyndiminnisfundir eru aðeins mögulegir fyrir nákvæmar forskeytissamsvaranir innan kvaðningar. Til að nýta kosti skyndiminnis, settu kyrrstætt efni eins og leiðbeiningar og dæmi í upphaf kvaðningarinnar og breytilegt efni, svo sem notendasértækar upplýsingar, í lokin. Þetta á einnig við um myndir og verkfæri, sem þurfa að vera eins á milli beiðna.

Með þetta í huga skulum við skoða hvaða tegundir aðgerða gætu valdið „skyndiminnis-missi“ í Codex:

• Að breyta tools sem eru tiltæk fyrir líkanið á meðan á samtalinu stendur.
• Að breyta líkan sem er markmið Responses API beiðninnar (í reynd breytir þetta þriðja atriðinu í upprunalegu kvaðningunni, þar sem það inniheldur leiðbeiningar sem eru sértækar fyrir líkanið).
• Að breyta stillingum sandkassans, samþykkisstillingu eða núverandi vinnuskrá.

Codex-teymið verður að vera vandvirkt þegar nýir eiginleikar eru kynntir í Codex CLI sem gætu haft áhrif á skyndiminni kvaðninga. Sem dæmi kynnti upphaflegur stuðningur okkar við MCP-verkfæri galla þar sem okkur mistókst að telja upp verkfærin í samræmdri röð⁠(opnast í nýjum glugga), sem olli skyndiminnisslysum. Athugaðu að MCP-verkfæri geta verið sérstaklega erfið þar sem MCP-netþjónar geta breytt listanum yfir verkfæri sem þeir bjóða upp á skyndilega með notifications/tools/list_changed⁠(opnast í nýjum glugga) tilkynningu. Að virða þessa tilkynningu í miðju langvarandi samtals getur valdið dýru skyndiminnisbroti.

Þegar mögulegt er, meðhöndlum við stillingabreytingar sem eiga sér stað í miðju samtali með því að bæta nýju skilaboði við input til að endurspegla breytinguna frekar en að breyta eldri skilaboðum:

• Ef stillingar sandkassans eða samþykkisstillingurinn breytist, setjum við inn⁠(opnast í nýjum glugga) ný skilaboð role=developer með sama sniði og upprunalega <permissions instructions> atriðið.
• Ef núverandi vinnuskrá breytist setjum⁠(opnast í nýjum glugga) við inn ný role=user skilaboð með sama sniði og upprunalega <environment_context>.

Við leggjum okkur fram við að tryggja skyndiminnisfundi til að bæta frammistöðu. Það er önnur lykilauðlind sem við verðum að stýra: samhengisglugginn.

Almenn stefna okkar til að forðast að samhengisglugginn klárist er að þjappa samtalinu þegar fjöldi tókar fer yfir ákveðinn þröskuld. Nánar tiltekið skiptum við út input fyrir nýjan, minni lista yfir atriði sem eru dæmigerð fyrir samtalið, sem gerir fulltrúanum kleift að halda áfram með skilning á því sem hefur gerst hingað til. Fyrri útfærsla á þjöppun⁠(opnast í nýjum glugga) krafðist þess að notandi kallaði handvirkt á /compact skipunina, sem myndi senda fyrirspurn til Responses API með því að nota núverandi samtal ásamt sérsniðnum leiðbeiningum fyrir samantekt⁠(opnast í nýjum glugga). Codex notaði skilaboð aðstoðarmannsins sem innihéldu samantektina sem nýtt inntak⁠(opnast í nýjum glugga) fyrir næstu umferðir samtalsins.

Síðan þá hefur Responses API þróast til að styðja sérstakan /responses/compact endapunkt⁠(opnast í nýjum glugga) sem framkvæmir þjöppun á skilvirkari hátt. Það skilar lista yfir atriði⁠(opnast í nýjum glugga) sem hægt er að nota í stað fyrra input til að halda áfram samtalinu á meðan samhengisglugginn er losaður. Þessi listi inniheldur sérstakan type=compaction hlut með ógegnsæjum encrypted_content hlut sem varðveitir leynda skilning líkansins á upprunalega samtalinu. Nú notar Codex sjálfkrafa þennan endapunktinn til að þjappa samtalinu þegar auto_compact_limit⁠(opnast í nýjum glugga) er farið yfir.

Við höfum kynnt Codex-fulltrúalykkjuna og útskýrt hvernig Codex mótar og stýrir samhengi sínu þegar það spyr líkan. Á leiðinni lögðum við áherslu á hagnýt atriði og bestu starfsvenjur sem eiga við alla sem eru að byggja fulltrúalykkju ofan á Responses API.

Þótt fulltrúalykkjan leggi grunninn að Codex, er það aðeins upphafið. Í komandi færslum munum við kafa í högun CLI, kanna hvernig notkun verkfæra er útfærð og skoða nánar sandkassalíkan Codex.