Практычныя нататкі: семантычны пласт — пласт сэнсу для вашага AI-агента

У гэтым керавану практычнаю праця перадаецца шлях ад сыр'ёў да рабочай сістэмы для: Семантычнага шару, адказанае на пытанне: Шар значэння, які трэба вашам AI-агентам. Акцэнт ставіцца на практычныя крокі, чыстае перакананне і код, які можна проста дадзіць у рэпазітарый без неабяснення меты. У стадыўцы агульнага відзору неабходна практычная апісацыя вхідных дадзеных, адпаведальнага за крок і крэатарных крытарыяў пры перадзеі коду. Аператары должны магчымаць перзапуск кроку з вядомай точкі контролю без неабяснення схованага стану. Конфігурацыю трэба зберагчы за межамі коду прыкладнення. Файлы сераў, хранільнікі секрэтных дадзеных і флагі функцыяў должны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць без неабяснення всіх аспектаў.

Што вы навучыцеся

Калі працюеце над этапам «Што вы научыцеся», спачатку запісайце умовы кантракта: неабяжлівыя даны, сігнал успеху і тое, што выканаецца у разе частковага невыпалення. Такі спіс контроля дапамагае заліцварыць змяны коду пазнейша.

Што на самай працэ ёсь кантэкставы слой

Калі працюеце над стадзіяй «Што такое семантычны слой», спачатку запісайце умовы працы: неабяжлівыя даны, сігнал успеху і тое, што выходзіць пад частковыя аберанціі. Такі спіс контроля дапамагае залічваць змяны ў кодзе чыста. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшае, аберанцыя должна вказваць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцюг задач. Зробіце пераконтроль пасля дорогіх крокаў. Програма не должна зноў ставіць плату за той самы вызов LLM, калі аператар праказвае спробу на болей пазнім элеменце.

Семантычны слой проты слоя метрык і модэлю дадзеных

Калі працюеце над стадзіяй «Семантычны слой» проты «Метрыкі», спачатку запісайце контракт: неабяжлівыя вхідныя даны, сігнал успеху і тое, што выходзіць у разе частковага невыпання. Такі спіс контроля дапамагае заліцьварыць пазнейшыя змены ў кодзе. Спрэцьвачайце гэтую стадзію як контракт межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Дайце назвы артыфактам, задаце правіла пераканання успеху і адмовіцеся ад тыхоўскага частковага завершэння. Зберагачыце у кешы стабільныя інструкцыі сістэмы і схемы інструментаў. Перадача ідэнтычных прамуров ёсць частым выклікам расходавання рэсурсаў. Калі працюеце над стадзіяй «Семантычны слой» проты «Метрыкі», спачатку запісайце контракт: неабяжлівыя вхідныя даны, сігнал успеху і тое, што выходзіць у разе частковага невыпання. Такі спіс контроля дапамагае заліцьварыць пазнейшыя змены ў кодзе. Зберагачыце настройкі параду ўнутры коду прыемлівача. Файлы сераўнавання, хранільнікі секрэтных дадзеных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць адбавіць аўдыт без неабяжлівага чытання всей структуры.

Краткая історыя, каб вы зналі, што насправды нова

Краткая історыя дапамагае, каб працэс працаваў наякша, калі яго спрыяваць як мерыемую паверхню. Запісаце адна «золатая» транскрыпцыю, адзін прыклад неудачы і прыметку па адвярненню працы перш чым расшырваць масштаб. Документаваце як успішны, так і вярнучы паты. Перапрыбуткі, людзкія контралі і обработка некорэктных паведамленняў ёсць часткай продукту, а не наступным этапам дапрацоўкі. Храніце стан графаў у простам і тыпаваным фармаце. Вкладзеныя блокі маскуюць, які вузел запісаў канкрэтны поле, і спакшваюць продовжэнне працы пасля перарываў.

Чаму агенты зробілі семантычны слой обавязковым

Агенты тыпу „Why“ даюць максімальны эфект, калі ўсё розглядаецца як вімерна паверхня. Зафіксуйце адну „золатую“ транскрыпцію, адын прыклад неудачы і прыметку па вярнэнню да поперадньего стану, прычаму расшырэння масштаба. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выходзіць, прычына неудачы павінна вказываць на адную адпаведальнасць, а не на заплутаны ланцюг задач. Рэзультаты працы графа павінны быць простымі і атрыбутаванымі. Вкладзеныя структуры маскуюць інфармацыю пра тое, які вузел запісаў які поле, і спакоююць працу пасля перэрываў.

Чатыры складнікі семантычнага шару

Чатыры складовыя стадзіі працуюць наўжоўды лепш, калі іх спрыяваць як мераемую паверхню. Зберагуйце адны ідэальны прыклад, адзін кейс неудачы і запіс пра вярнэнне да пачатковага стану перад расшырэнням масштаба. Спрыяйце гэтай стадзіі як кантракту межаў вхідных дадзеных і перакананых выходных рэзультатаў. Даўце назвы артыфактам, задаць крытэрыя успеху і адмовіцеся ад тыхнага частковага завершэння без паведамлення. Храніце стан графа ў простым і тыпаванам фармаце. Вкладзеныя блокі маскуюць інфармацыю пра тое, які вузел запісаў кожны поле, і спакшуюць возз'яданне пасля перарываў. Чатыры складовыя стадзіі працуюць наўжоўды лепш, калі іх спрыяваць як мераемую паверхню. Зберагуйце адны ідэальны прыклад, адзін кейс неудачы і запіс пра вярнэнне да пачатковага стану перад расшырэнням масштаба. Храніце настройкі за межамі коду прыемлівача. Файлы сераўнавальнага сераўса, хранілішчы секрэтных дадзеных і флагі функцыйяў должны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць без неабходнасці чытання всего графа.

# A metric defined for an agent, not just a tooltip
metrics:
  - name: revenue
    label: Net Revenue
    description: >
      Recognized net revenue. Gross order amount minus refunds
      and partner discounts. Excludes the 'internal' segment.
    calculation: SUM(orders.amount - orders.refund_amount
                     - orders.partner_discount)
    filters:
      - customers.segment != 'internal'
    time_grain: [day, week, month, quarter]
    fiscal_calendar: offset_aug   # fiscal year starts Aug 1

Headless проты embedded — і чаму гэта зараз мае большое значэнне

Для варыянтав «без галавы» протыра ўвязанага і на стадзіі, паказвайце вхідныя даны, адпаведальнага за крок і крэтыяры завершэння пры перадзеі коду. Аперацыйныя працавнікі павінны магчымае перазапускаць крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Дакументавайце як шлях успеху, так і шлях вярнення. Перапрыбуткі, людзкіе контралі і обработка некорэктных паведамленняў ёсць часткай продукту, а не пасляднім дапрацоўкам. Наводзіце часткі тэксту, якія фактычна лежалі в основе адпаведнай адказы. Без цых цітатаў аперацыйныя працавнікі не зможуць адразніць галюцынацыю ад прасоў у індэксаванні.

Дзе паслужае семантычны слой: тры слоі, а не адзін

У стадыі семантскага шару неабяжна ўзначыць вхідныя даны, адпаведальнага за крок і крытэрыя завершэння пры зміне коду. Аперацыйныя працавнікі павінны магчымае перазапускаць крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Лепш выбіраць маленькія, тэставаныя елементы замест большых скрыптов. Калі крок не выйшоў, прычына нехарактэрыстыкі павінна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцужок задач. Неабяжна ўключыць людзкія пераказы для тых крокоў, якія вітрачаюць грошы або зменяюць даны ў працэсе віробніцтва. Праця ў часе компілявання не абавязкова значыць повнайшую рэалізацыю бізнес-функцый.

Што семантскі шар не можа зробіць сам

Для этапы «What a semantic layer» неабяжна ўзначыць вхідныя даны, адпаведальнага за крок і крэтырыя завершэння пры зміне коду. Аперацыйныя працавнікі должны магчымае перайсці гэты крок з вядомага пункта контролю, не спрабоўваючы здагадвацца пра схованы стан. Спрацавляйце гэтую стадыю як кантракт межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Даўце назвы артыфактам, узначыце перакананні пра успех і адмовіцеся ад беззвучнага частковага завершэння. Заставьце людзкія падтверджэння для тых крокоў, якія выкарыстоўваюць грошы або зміняюць даны для працы. Компіляцыйныя налашчэння не ўзначаюць павнае завершэння бізнес-працэсаў. Для этапы «What a semantic layer» неабяжна ўзначыць вхідныя даны, адпаведальнага за крок і крэтырыя завершэння пры зміне коду. Аперацыйныя працавнікі должны магчымае перайсці гэты крок з вядомага пункта контролю, не спрабоўваючы здагадвацца пра схованы стан. Зберагайце налашчэнні параду аплікацыйскага коду. Файлы сераўіса, хранільнікі секрэтных дадзеных і флагі функцыйяў должны знаходзіцца ў аднам месцы, якое працавнікі можу аўдытаваць, не чытаючы весь граф.

-- Question: "What was our Q3 revenue?"

-- (A) Schema-only: the agent guesses
SELECT SUM(amount) AS revenue
FROM orders
WHERE order_date BETWEEN '2026-07-01' AND '2026-09-30';
-- → $14.2M   includes refunds + partner discounts, wrong fiscal quarter

-- (B) Grounded in the semantic layer's definitions
SELECT SUM(o.amount - o.refund_amount - o.partner_discount) AS revenue
FROM orders o
JOIN customers c ON c.customer_id = o.customer_id
WHERE c.segment <> 'internal'
  AND o.order_date BETWEEN '2026-08-01' AND '2026-10-31'; -- fiscal Q3
-- → $11.0M   net revenue, external customers, correct fiscal calendar

Тыпы кантэкста, якія знаходзяцца параду ў будзь-якай модэлі дадзеных

Калі працуеце над этапам «Тыпы кантэкста», спачатку запісайце умовы вікорыстання: неабяжлівыя даныя, сігнал успеху і тое, што выканаецца у разы частковага невясковасці. Такі спіс дапамагае залічыць змяны ў кодзе пазнейша. Документавайце як шлях успеху, так і шлях вясковасці адночасна. Перапрыбуткі, людзкі контроль і обработка некорэктных паведамленняў ёсць часткай продукту, а не дадатковымі правкамі пазнейша. Зберагайце у кэшы стабільныя інструкцыі сістэмы і схемы інструментаў. Перасылка ідэнтычных паведамленняў ёсць частым выкліком для рэсурсаў.

Тры рэалістычныя стратэгіі для ўзьмечання адной

Калі працюеце над Трымаям рэалістычнымі шляхамі да стадзіі, спачатку запісайце контракт: неабяжлівыя даныя, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі спіс пераконтроўкі дапамагае заліцвачваць пазнейшыя змены ў кодзе. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшоў, нявыпанне павінна вказваць на адную адпаведальнасць, а не на заплутаны ланцужок задач. Зробіце пераконтроўку пасля дорогіх крокаў. Програма для продакцыі не павінна зноў выклікаць той самы калл LLM, калі аператар праканае пазнейшы вузел.

Шлях 1 — Стварыце ў dbt

Калі працуеце над стадзіяй «Path 1 Build it», спачатку запісайце контракт: неабяжлівыя даныя, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі спіс пераконвае ў тым, што пазнейшыя змены коду будуць чыстымі. Спрэчвайце гэтую стадзію як контракт межа данымі і перакананымі выходамі. Дайце назву артыфактам, задацье правіла пераканання успеху і не падзэліваецеся на частковыя завершэння без паведамлення. Зробіце контрольную точку пасля дорогіх крокаў. Сістэма вярнення не павінна зноў ставіць плату за той самы вызов LLM, калі аператар прабуе зноў запрацаваць пазнейшы вузел. Калі працуеце над стадзіяй «Path 1 Build it», спачатку запісайце контракт: неабяжлівыя даныя, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі спіс пераконвае ў тым, што пазнейшыя змены коду будуць чыстымі. Зберагаеце настройкі паза кодам прыемлі. Файлы сераўнавання, хранільнікі секрэтных дадзеных і флагі функцыйяў павінны знаходзіцца ў аднам месцы, куда аператары можаць адбавіць аўдыт без неабяжлівага чытання всей структуры.

Path 2 — Адмаціраванне безгалавай платформы

Этап «2. Выбір спосабу» працюе найкрашча, калі яго розглядаць як вімерную паверхню. Запісаце адзін успешны прыклад, адзін прыклад неудачы і прыметку паўранення перш чым расшырваць масштаб. Дакументаваце як успешны, так і патэнціяльны шляхы рашэння проблем. Перапрыбуткі, людзкія контрольны пункты і обработка некорэктных паведамленняў ёсць часткай продукту, а не наступным етапам дапрацоўкі. Храніце стан графа ў простам і тыпаваным фармаце. Вкладзеныя блокі маскуюць інфармацыю пра тое, які вузел запісаў канкрэтны поле, і спакшуюць продовжэнне працы пасля перарываў.

Шлях 3 — Кодаванне кантэксту безпосерэдна

Этап кантэкстнай кодавання Path 3 работае наяўней, калі яго спрыяваць як мерыемую паверхню. Зафіксавайце адна ідэальная транскрыпцыя, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расшырваць масштаб. Валіце малыя, тэставаныя елементы замест большых скрыптов. Калі якісьць кроку не выходзіць, прычына неудачы павінна вказываць на адную адпаведальнасць, а не на заплутаны ланцюг задач. Рэзервавайце стан графа ў простам і тыпізаваным фармаце. Вярнутыя структуры маскуюць інфармацію пра тое, які вузел запісаў канкрэтны поле, і спакшуюць продаж чыннасці пасля перэрываў.

Памылкі, якія робяць команды ў эпас агентаў

Этап, дзе команды дармачаць, працуе наяўней калі яго спрыяваць як мерыемую паверхню. Запісаце адны ідэальны прыклад, адзін кейс неудачы і прыметку па вярнэнню да пачатковага стану пры расшырэнні масштаба. Спрыявайце гэты стадыю як кантракт межа вхіднымі дадзеннямі і паверыжанымі выходнымі рэзультатамі. Даўце назвы артыфактам, задаце крытэрыя успеху і адмовіцеся ад тыхоўскага частковага завершэння. Храніце стан графа ў простам і тыпаваным фармаце. Вярнутыя структуры маскуюць, які вузел запісаў канкрэтны поле, і спакшваюць продаж чыненняў пасля перарываў. Этап, дзе команды дармачаць, працуе наяўней калі яго спрыяваць як мерыемую паверхню. Запісаце адны ідэальны прыклад, адзін кейс неудачы і прыметку па вярнэнню да пачатковага стану пры расшырэнні масштаба. Храніце настройкі за межамі коду прыемліка. Файлы сяродавішча, хранальнікі секрэтных дадзенняў і флагі функцыйяў должны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць без неабходнасці чытання всего графа.

Куды гэта прыводзіць

На стадыі «Дзе гэта будзе выканана» неабяжна практычна апісацыя вхідных дадзеных, адпаведальнага за крок і крэтарыя выходу пры перадзеіснаванні коду. Аператары должны магчымаць перзапуск кроку з вядомай точкі контролю, не спрабоўваючы здагадвацца пра схованы стан. Неабяжна задокументаваць як «успешны» так і «восстанавліваючыся» маршруты. Перапрыбуткі, людзкія пераказы і апрацоўка некорэктных паведамленняў ёсць часткай продукту, а не элементамі пазнейшага дапрацоўкі. Неабяжна прыняць людзкую згоду для тых крокоў, якія выкалічваюць грошы або зменяюць даны варабочай сістэмы. Кампіляцыйныя налашчанні не ўзроўнаўцуюцься з павнайсткамаснасцю бізнес-процэсаў.

Чэк-ліст для эксплуатацыі

Стадыя чэк-ліста для эксплуатацыі працюе наякшэ, калі яе спрыймаюць як мерыемую плошчу. Перад расшырэнням масштаба неабяжна зафіксаваць адну «золатую» транскрыпцыю, адын прыклад неудачы і прыметкі па вярнэнню да пачатковага стану.

Запісваць часы выканання і косты токеноў або запытак разам з функцыйнальнымі рэзультатамі. Відкрытая інформацыя пра косты з’являецца ранішэ, чым утвараюцца неспадзянанні з боку расчыткаў, калі маршрут пераходзіць з дэмовай сістэмы ў спяльныя сераўеры.

Зберагаюце стан графа ў простам і тыпаваным фармаце. Вкладаныя блобы маскуюць інфармацію пра тое, які вузел запісаў якое поле, і спакошуюць продовжэнне працы пасля перэрываў.

Калі дозволяе бюджэт, дадзіце тэст на перакананне, які працюе з крытычным шляхам у CI за дапамою фікстураў, а не рэальных платных API.

Конфігурацыю трэба зберагаць паза кодам прыкладнай програмы. Файлы сераўнавання, хранільнікі секрэтных даных і флагі функцыяй должны знаходзіцца ў аднам месцы, куда аператары можуць аўдытуваць іх без неабяжнага чытання всего графа.

Зберагаюце стан графа ў простам і тыпаваным фармаце. Вкладаныя блобы маскуюць інфармацію пра тое, які вузел запісаў якое поле, і спакошуюць продовжэнне працы пасля перэрываў.

Перш чым апранаваць стэк, заморозьце версіі, зафіксуйце ідэальны транскрыпт для крытычнага шляху і паказваце крокі для атрыбутавання. У спакульнаваных сераўнаваннях неабходны ліміты швайнасці, перакананні ў прыналежнасці і чыстае вялоўнік для змены секрэтных даных. Валіце надзейнасць працы над красавім разовым дэманстрацыйным прыкладам.

Запіскі для пакета be8d2aacd117: не класты ключы прадаўцоў у рэпазітарыю, задаць максымальны ліміт токена на кожную сесію, а таксама зберагчы транскрыпціі праза фіксатуры адлічэння, каб пазнейшыя замены мадэляў заставаліся порównанымі.