OKF + RAG: гібрыдная архітэктура для надзейных AI-агентаў

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

Стандартным рашэннем за апошнія два гады быў метод RAG: падключэнне мадэлі да вектарнай базы дадзеных з дакументамі компаніі, выявленне таго, што выглядае рэлевантным, і ўкладкі гэтага матэрыялу ў запіт. Гэты метод працюе для вялікіх кантэйнероў неструктураванага тэксту. Яго слабасць у тым, што ён ёсць верагатычным — ён вяртае абдзяцкі, сэмантычна супадаючыя з запытам, але гэта не тое ж самае, што абдзяцкі, якія ёсць автантычнымі. Калі запыт стосуецца офіцыйной формулы выручкі чы умов контракту з пунктом адплатаў, проста супадання недастатнья.

У чэрвені 2026 года Google Cloud адкласіла фармат адкрытых ведамаў (OKF) – спецыфікацыю, нейтральную ўжытку з боку віробнікаў, для куратаваных ведамаў, якія зберагаюцца у файлах фармата Markdown. Спалучыўшы ўжо існуючыя можлівасці точнага пошуку з шырокім дасягненням тэхналогіі RAG, мы отрымаема архітэктуру, якая можа стаць выборам для агентаў, якія павінны быць адночасна тачнымі і здатнымі да дакладнага аналізу.

Две памяці

Уявіце новага працавніка ў яго першы дзень. Перад ям расставляюцца два элементы.

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

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

Ні адны з этых спосабоў сам по сабе недастатні. Разам яны пакрываюць весь спектр таго, што ведае арганізацыя.

Што такое OKF

OKF ўмышлена просты. «Пакет» — гэта каталог файлаў у фармаце Markdown, якія зберагаюцца ў Git. Кожны файл опісвае адну концэпцыю — напрыклад, табліцу, паказнік, канец API або інструкцыю, і пачынаецца з блока YAML-метаданых, якія можна прачытаць машынай. Спецыфікацыя не вімагае многа ад тых, хто стварае такія файлы, а такія інструменты, як Obsidian, Notion чы MkDocs, ужо падтрымліваюць такі фармат файлаў. Праект знаходзіцца ў публічным рэпазітарыі.

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

---
type: metric
title: "Monthly Churn Rate"
description: "Official formula for calculating monthly customer churn."
owner: "data-engineering"
tags: [revenue, kpi, board-report]
timestamp: 2026-06-20T10:00:00Z
---

# Monthly Churn Rate

The official churn rate formula used in all board reports and investor decks:

    Churn Rate = (Customers Lost During Month / Customers at Start of Month) × 100

### Rules
- **Do NOT** use trial accounts in the denominator.
- **Do NOT** count plan downgrades as churn.
- Source of truth: `analytics.monthly_churn_summary` table.

### Related
- [Monthly Active Users](mau.md)
- [Revenue Dashboard](revenue_dashboard.md)

Чаму взагалі трэба гэта робіць?

• Няма матэматыкі вектараў. Калі агенту патрэбна формула, ён чытае тыя файлы безпосерэдна. Няма вбудоввання, няма рэйтынгу сэроднечы і няма механізма top-k — ўсё час адпаведзае толькі затверджаныя адпаведзенні.
• Інтэгруецца з рабочымі працэсамі Git. Змяны праходзяць праз запросы прыўязкі, перагляды і історыю зберагання, таму існуе журнал аўдыту, які паказвае, хто, калі і чаму змяніў формулу.
• Няма інфраструктуры. Няма хранілішча вектараў, праграмы для стварэння вектараў, стратэгіі разбівання на часткі чы ўпорадкування. Файлы знаходзяцца ў папцы.

Што такое RAG

RAG з’яўляе зв’язак межа модэлем і вялікімі, неструктураванымі дадзеннямі за шэсць крокаў:

1. Прыймаюцца дакументы, такія як PDF-файлы, электранаўпы, сторанкі wiki і паведамленні ў чаце.
2. Яны разбіваюцца на менжыя часткі.
3. Кожная частка ператвараецца на вектар за дапамогою модэля стварэння вектараў.
4. Вектары зберагаюцца ў базе дадзеных, такій як Pinecone, Weaviate чы pgvector.

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

Дыявэтыя фрагменты трэба дадаць у запрошэнне, каб мадэль могла даць адказ у кантэксце.

Сілой RAG ёст колькасць доступных матэрыялаў. Ён можа выявіць рэлевантныя даныя з тыяў тысяч дакументаў, якія ніхто не змог бы аранжаваць вручную. Яго слабасцю ёст тачнасць. Паколькі для пошуку вікорыстоўваецца супаданне, ён можа вярнуць тэкст, які ёсць супаўзменны, але не ёсць автантычным. Якшча тры разныя падходы адночасна даўнае падаюць на разны спосаб, RAG можа выбраць неправільны варыянт.

Гібрыдны дызайн

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

Спрасцаваная версія гэтага рутэра на Python выканае чатыры задачы. Яна завантажвае кожны файл у фармаце Markdown з пакета і стварае індэкс з іх загаванак, якія знаходзяцца ў філдзе frontmatter. Пасля гэтага адбываецца прабава пашуку ключоўых слоў запіту сярод гэтых загаванак. Калі такі спосаб знаходзіць відпаведны пункт, тады контэнт перадаецца з пазначэннем, што ён походзіць з офіцыйнай базы знанняў. У працоўных случаях вікорыстоўваецца векторны пошук, пазначаны як пошук дакументаў, пасля чаго выбраны кантэкст адправляецца да модэля з інструкцыяй адпавядаць толькі на адпаведны запіт. Пазначэнне вучынніка ў запытэ мае важлівэ значэнне, адтолькі як гэта паведамляе модэль, а пазней і чытальніка, якую вагу павінен мець той кантэкст.

from openai import OpenAI
import os
import glob
import yaml

client = OpenAI()

# 1. Load the OKF knowledge bundle from the local directory
def load_okf_bundle(bundle_path: str) -> dict:
    """Reads all Markdown files in the OKF directory into a searchable dict."""
    knowledge = {}
    for filepath in glob.glob(f"{bundle_path}/**/*.md", recursive=True):
        with open(filepath) as f:
            content = f.read()
            # Extract the title from YAML frontmatter
            if content.startswith("---"):
                _, frontmatter, body = content.split("---", 2)
                meta = yaml.safe_load(frontmatter)
                title = meta.get("title", os.path.basename(filepath))
                knowledge[title.lower()] = body.strip()
    return knowledge

# 2. Search OKF (deterministic, keyword-based)
def search_okf(query: str, okf_knowledge: dict) -> str | None:
    """Simple keyword match against OKF titles."""
    for title, content in okf_knowledge.items():
        if title in query.lower():
            return content
    return None

# 3. Search RAG (probabilistic, vector-based)
def search_rag(query: str) -> str:
    """Placeholder for your vector DB search (Pinecone, Weaviate, etc.)."""
    # results = vector_db.similarity_search(query, top_k=5)
    return "RAG context: [retrieved chunks would appear here]"

# 4. The Intelligent Router
def answer_query(query: str, okf_bundle_path: str) -> str:
    okf_knowledge = load_okf_bundle(okf_bundle_path)

    # Try OKF first (deterministic path)
    okf_result = search_okf(query, okf_knowledge)

    if okf_result:
        context = f"[SOURCE: Official Knowledge Base (OKF)]\n{okf_result}"
    else:
        # Fall back to RAG (probabilistic path)
        context = f"[SOURCE: Document Search (RAG)]\n{search_rag(query)}"

    # Send to LLM with the retrieved context
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "Answer using ONLY the provided context."},
            {"role": "user", "content": f"Context:\n{context}\n\nQuestion: {query}"}
        ]
    )
    return response.choices[0].message.content

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

Вывык

Для корпаратыўных агентаў не існуе выбору между OKF і RAG. Найэфектывнейшы дызайн выкарыстоўвае аба падходы. Дэтэрміністычная база знанняя, кантролюемая Git, захоўвае тыя факты, якія не можаць быць некорэктнымі: KPI, угоды API і інструкцыі па працы. Правалентны пошук вектараў паводзіцца з вялікім архівам неструктураванага матэрыялу, які ніхто не можа адсортаваць. Рэзультатам яе ёсць агент, які ўсё правільна вырахоўвае, калі важна тачнасць, і дапамагае у доследжэннях, калі важна адкрыцце.