Шлюз және бұрылыс қозғалтқышы

AiHummer-дің жүрегі — жалғыз шлюз қызметі. Ол бір мезгілде басқару-жазықтығы (әкімші API, баптаулар, арнаны жалғау, маркетплейс) әрі бұрылыс қозғалтқышы (жауап өндіретін функция-шақыру циклі) болып табылады. Сондықтан типтік орналастыру — тек сол бір қызмет пен PostgreSQL — сіз іске қосуға міндетті бөлек жұмысшы деңгейі жоқ.

Бір қызмет, екі рөл

Шлюз әдепкі бойынша :8780 портында тыңдайды, оны AIHUMMER_GATEWAY_ADDR басқарады. Орнатушы басқа бос портты таңдауы мүмкін, бірақ процесс әрқашан сол бір жалғыз қызмет болып қала береді.

# gateway.env — the only required setting
AIHUMMER_DATABASE_URL=postgres://user:pass@localhost:5432/aihummer?sslmode=disable
# Admin UI after start at http://localhost:8781/

Жалғыз қатаң тәуелділік — PostgreSQL. Postgres — шындықтың жалғыз көзі: агенттер, баптаулар, әңгімелер, жад, outbox және аудит — бәрі сонда тұрады. Қалғаны — sidecar-лар, вектор қоймасы, хабарлама шинасы, модель жеткізушілер — қосымша және оны конфигурациялаған кезде ғана жалғанады.

[!NOTE] Дерекқорсыз шлюз тек-денсаулық режимінде іске қосылады: ол GET /healthz-қа жауап береді, осылайша оркестратор немесе жүктеме теңгерімдеуіш процестің тірі екенін көре алады, бірақ ол бұрылыстарды өңдемейді. GET /readyz PostgreSQL-ді тексереді және дерекқор қол жетімсіз болғанда 503 қайтарады.

Іске қосылу кезінде не болады

Іске қосылу кезінде шлюз бірнеше қадамды қатаң ретпен орындайды:

дерекқор қосылым пулын ашады,
Postgres advisory құлпы астында кез келген күтудегі көшіруді қолданады,
конфигурацияны шешеді (дерекқор мәні → орта айнымалысы → ішкі әдепкі), және
қызметтерді — маршрутизатор, оркестратор, арналар, құралдар, жад, жеткізу — жұмыс істеп тұрған шлюзге жалғайды.

Маңызды салдар — көптеген мүмкіндіктер баптау кілті арқылы таңдамалы. Конфигурацияланбаған мүмкіндік жай ғана белсендірілмейді, бұл әдепкі орындалу ортасын шағын әрі болжамды сақтайды. Сіз оларды веб-әкімші UI-дан немесе AIHUMMER_* айнымалысымен қосасыз, ал шлюз оларды келесі іске қосылуда шешеді (немесе мұны қолдайтын реттегіштер үшін қызу күйде).

Бұрылыс қозғалтқышы

Хабарлама шлюзге жеткенде, бұрылыс қозғалтқышы билікті алады. Ол функция-шақыру циклін іске қосады: модельге жүйелік шақыру мен әңгіме беріледі, ол құралдарды шақыруы мүмкін (немесе ішкі-агенттерді тудыруы), әр құрал нәтижесі кері беріледі, ал цикл модель соңғы жауапты өндіргенше жалғасады. Содан соң сол жауап жеткізу қабатына беріледі.

inbound message
   └─▶ turn engine
         ├─ assemble layered system prompt
         ├─ call model ──▶ tool calls / sub-agents ──▶ tool results ─┐
         │       ▲                                                    │
         │       └────────────────────────────────────────────────-─┘
         └─ final answer ─▶ outbox ─▶ originating channel

Цикл әр кірістің қайдан келетіні туралы детерминистік болғандықтан, жауаптар әңгіме тарихынан және құрал нәтижелерінен шешіледі — нұсқауларға сенімсіз мәтінді ешқашан еңгізу арқылы емес. Дәл осы қасиет төмендегі шақыру қабаттауын әрі қауіпсіз, әрі жылдам етеді.

Қабатты, кэш-достық жүйелік шақыру

Жүйелік шақыру — бір тұтас түйір емес. Ол қабаттармен құрастырылады, тұрақты бөліктер бірінші, ал құбылмалы бөліктер соңғы болатындай етіп әдейі реттелген. Бұл маңызды, өйткені модель жеткізушілер шақыруды оның префиксі бойынша кэштейді: шақырудың басы байт-байтқа бірдей болғанша, кэштелген префикс қайта пайдаланылады және тек құйрық қайта өңделеді.

Аймақ	Қабаттар (ретімен)	Өзгереді…
Тұрақты префикс (кэштелетін)	базалық сәйкестік + құрал/жад нұсқаулығы → жалдаушы → персона → дағдылар	сирек — агент/жалдаушы бойынша
Құбылмалы құйрық (соңғы қосылады)	онбординг күйі → жадты толтыру → тірі күн	әр бұрылыста

Тұрақты префикс агенттің кім екенін анықтайтын барлық нәрсені алып жүреді: ішкі сәйкестік пен құралдар мен жадтың қалай жұмыс істейтінінің нұсқаулығы, содан соң жалдаушы қабаты, агенттің персонасы және рендерленген дағдылар блогы. Оның ешқайсысы сол агенттің екі дәйекті бұрылысы арасында өзгермейді, сондықтан ол қайта пайдаланылатын кэштелген префикс құрайды.

Құбылмалы құйрық тұрақты префикстен кейін дәл сол кэшті ешқашан жарамсыз етпейтіндей қосылады: онбординг күйі, осы нақты әңгіме үшін толтырылған жад және ағымдағы күн — бәрі бұрылыстан бұрылысқа өзгереді, бірақ олар соңында тұрғандықтан, тек қосқанын ғана құнға салады.

[!TIP] Дәл осы реттеу — бүгінгі күн сияқты тірі деректің әр бұрылыста бүкіл сәйкестікті қайта кодтауға төлемей-ақ бола алуының себебі. Агент-бойынша теңшелетін мазмұнды тұрақты қабаттарда (персона, дағдылар) сақтаңыз да, құбылмалы құйрықты қозғалтқышқа иелетіңіз.

Әрі қарай қайда

Жалдаушылардың қалай оқшауланатынын мынадан қараңыз: Көп-жалдаушылық және идемпотенттілік.
Жауаптардың қалай қайтарылатынын мынадан біліңіз: Жеткізу, outbox және қалпына келтіру.
Қосымша мүмкіндіктер Sidecar-лар ретінде іске қосылады.