Gateway და ბრუნვის ძრავა

# 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/

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

AiHummer-ის გული არის **ერთი gateway სერვისი**. ის ერთდროულად არის **control-plane** (ადმინ API, პარამეტრები, არხის გაყვანილობა, marketplace) და **ბრუნვის ძრავა** (ფუნქცია-გამოძახების ციკლი, რომელიც წარმოშობს პასუხს). ტიპური დანერგვა ამიტომ არის უბრალოდ ეს ერთი სერვისი პლუს PostgreSQL — არ არსებობს ცალკე worker დონე, რომელიც უნდა გაუშვათ. ## ერთი სერვისი, ორი როლი gateway უსმენს `:8780`-ზე ნაგულისხმევად, რასაც აკონტროლებს `AIHUMMER_GATEWAY_ADDR`. ინსტალატორმა შესაძლოა აირჩიოს განსხვავებული თავისუფალი პორტი, მაგრამ პროცესი ყოველთვის იგივე ერთი სერვისია. ```ini # 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-ები, ვექტორული საცავი, message bus, მოდელის პროვაიდერები — არჩევითია და გაყვანილია მხოლოდ მაშინ, როცა მას აკონფიგურირებთ. > [!NOTE] > მონაცემთა ბაზის გარეშე gateway იწყება **ჯანმრთელობა-მხოლოდ რეჟიმში**: ის პასუხობს > `GET /healthz`-ს ისე, რომ ორკესტრატორმა ან load balancer-მა დაინახოს, რომ პროცესი > ცოცხალია, მაგრამ ის არ მოემსახურება ბრუნვებს. `GET /readyz` ამოწმებს PostgreSQL-ს და > აბრუნებს `503`-ს სანამ მონაცემთა ბაზა მიუწვდომელია. ## რა ხდება გაშვებისას გაშვებისას gateway ასრულებს რამდენიმე ნაბიჯს მკაცრი თანმიმდევრობით: 1. ხსნის მონაცემთა ბაზის კავშირის pool-ს, 2. იყენებს ნებისმიერ მოლოდინში მყოფ მიგრაციას Postgres-ის advisory lock-ის ქვეშ, 3. წყვეტს კონფიგურაციას (მონაცემთა ბაზის მნიშვნელობა → გარემოს ცვლადი → ჩაშენებული ნაგულისხმევი), და 4. გაჰყავს სერვისები — router, orchestrator, არხები, ხელსაწყოები, მეხსიერება, მიწოდება — მომუშავე gateway-ში. მნიშვნელოვანი შედეგი არის ის, რომ **ფუნქციების უმეტესობა არჩევითია პარამეტრის გასაღების გავლით**. შესაძლებლობა, რომელიც არ არის კონფიგურირებული, უბრალოდ არ არის გააქტიურებული, რაც ინარჩუნებს ნაგულისხმევ runtime-ს მცირესა და პროგნოზირებადს. თქვენ ჩართავთ ნივთებს ვებ ადმინ UI-დან ან `AIHUMMER_*` ცვლადით, და gateway წყვეტს მათ შემდეგ გაშვებაზე (ან ცხელად, იმ სახელურებისთვის, რომლებიც ამას მხარს უჭერენ). ## ბრუნვის ძრავა როდესაც შეტყობინება მიაღწევს gateway-ს, ბრუნვის ძრავა იღებს მმართველობას. ის უშვებს **ფუნქცია-გამოძახების ციკლს**: მოდელს ეძლევა სისტემური prompt და საუბარი, მას შეუძლია ხელსაწყოების გამოძახება (ან ქვე-აგენტების წარმოშობა), თითოეული ხელსაწყოს შედეგი მიეწოდება უკან, და ციკლი გრძელდება სანამ მოდელი არ წარმოშობს საბოლოო პასუხს. ეს პასუხი შემდეგ გადაეცემა მიწოდების ფენას. ```text inbound message └─▶ turn engine ├─ assemble layered system prompt ├─ call model ──▶ tool calls / sub-agents ──▶ tool results ─┐ │ ▲ │ │ └────────────────────────────────────────────────-─┘ └─ final answer ─▶ outbox ─▶ originating channel ``` იმის გამო, რომ ციკლი დეტერმინისტულია იმაში, *საიდან* მოდის თითოეული შესასვლელი, პასუხები წყდება საუბრის ისტორიიდან და ხელსაწყოს შედეგებიდან — არასოდეს არასანდო ტექსტის ინსტრუქციებში ინექციით. სწორედ ეს თვისება ხდის prompt-ის ფენებად დაყოფას ქვემოთ უსაფრთხოს ისევე, როგორც სწრაფს. ## ფენოვანი, ქეშ-მეგობრული სისტემური prompt სისტემური prompt არ არის ერთი blob. ის აიწყობა ფენებად, განზრახ დალაგებული ისე, რომ **სტაბილური ნაწილები პირველ რიგში მოვიდეს და ცვალებადი ნაწილები ბოლოს მოვიდეს**. ეს მნიშვნელოვანია იმიტომ, რომ მოდელის პროვაიდერები ქეშავენ prompt-ს მისი პრეფიქსით: სანამ prompt-ის დასაწყისი ბაიტ-ბაიტ იდენტურია, ქეშირებული პრეფიქსი ხელახლა გამოიყენება და მხოლოდ კუდი მუშავდება ხელახლა. | ზონა | ფენები (თანმიმდევრობით) | იცვლება… | |---|---|---| | **სტაბილური პრეფიქსი** (ქეშირებადი) | საბაზისო იდენტობა + ხელსაწყო/მეხსიერების სახელმძღვანელო → tenant → persona → უნარები | იშვიათად — აგენტ/tenant-ზე | | **ცვალებადი კუდი** (ბოლოს ემატება) | ონბორდინგის მდგომარეობა → მეხსიერების ჰიდრაცია → ცოცხალი თარიღი | ყოველ ბრუნვაზე | სტაბილური პრეფიქსი ატარებს ყველაფერს, რაც განსაზღვრავს *ვინ არის აგენტი*: ჩაშენებულ იდენტობასა და სახელმძღვანელოს იმის შესახებ, თუ როგორ მუშაობს ხელსაწყოები და მეხსიერება, შემდეგ tenant ფენას, აგენტის persona-ს, და რენდერებულ უნარების ბლოკს. არცერთი ეს არ იცვლება ერთი და იმავე აგენტის ორ თანმიმდევრულ ბრუნვას შორის, ამიტომ ის ქმნის ხელახლა გამოყენებად ქეშირებულ პრეფიქსს. ცვალებადი კუდი ემატება სტაბილური პრეფიქსის **შემდეგ** ზუსტად იმისთვის, რომ მან არასოდეს გააუქმოს ქეში: ონბორდინგის მდგომარეობა, ამ კონკრეტული საუბრისთვის ჰიდრირებული მეხსიერება, და მიმდინარე თარიღი ყველა იცვლება ბრუნვიდან ბრუნვამდე, მაგრამ იმის გამო, რომ ისინი ისხდებიან ბოლოში, ისინი ღირან მხოლოდ იმდენი, რამდენსაც ამატებენ. > [!TIP] > ეს დალაგება არის მიზეზი იმისა, თუ რატომ შეიძლება ცოცხალი მონაცემები, როგორიცაა დღევანდელი თარიღი, იყოს > ყოველ ბრუნვაში ისე, რომ არ გადაიხადო მთელი იდენტობის ხელახალი დაშიფვრა ყოველ ჯერზე. შეინახეთ > მორგებული აგენტ-სპეციფიკური შინაარსი სტაბილურ ფენებში (persona, უნარები) და მიეცი > ძრავას ცვალებადი კუდის ფლობა. ## სად შემდეგ - ნახეთ, როგორ არიან tenant-ები იზოლირებული [მრავალმოიჯარეობა და იდემპოტენტურობა](/ka/v1.0/architecture/multitenancy-idempotency)-ში. - შეიტყვეთ, როგორ ბრუნდება პასუხები [მიწოდება, outbox და აღდგენა](/ka/v1.0/architecture/delivery-outbox)-ში. - არჩევითი შესაძლებლობები მუშაობს როგორც [Sidecar-ები](/ka/v1.0/architecture/sidecars).