OKF + RAG: Hybrydowa architektura dla niezawodnych agentów AI

Zadaj agentowi AI dobrze znany fakt, a on odpowie płynnie. Poproś go o dokładną formułę odchodzenia klientów w twojej firmie, schemat wewnętrznej API lub instrukcję postępowania w przypadku awarii bazy danych – może dostarczyć coś, co brzmi sensownie, ale jest w całości wymyślone. To jest problem halucynacji, który stanowi główny powód, dla którego firmy wahają się, czy powierzać agentom rzeczywiste zadania.

Standardową metodą ostatnich dwóch lat jest RAG: łączenie modelu z bazą wektorową dokumentów firmy, pobieranie tego, co wydaje się istotne, i wklejanie tego do promptu. Działa to przy dużych ilościach nieustrukturyzowanego tekstu. Jego wadą jest to, że jest probabilistyczne – zwraca fragmenty semantycznie podobne do pytania, co różni się od fragmentów autorytatywnych. Gdy pytanie dotyczy oficjalnej formuły przychodów lub umowy dotyczącej punktu końcowego płatności, podobieństwo nie wystarcza.

W czerwcu 2026 roku Google Cloud wprowadził Open Knowledge Format (OKF) – specyfikację neutralną pod względem dostawcy, służącą do przechowywania starannie przygotowanej wiedzy w plikach Markdown. Połączenie dokładnych wyszukiwań tego formatu z szerokim zasięgiem technologii RAG daje architekturę godną rozważenia dla agentów, które muszą być zarówno precyzyjne, jak i zdolne do eksploracji.

Dwie bazy pamięci

Wyobraź sobie nowego pracownika w jego pierwszym dniu pracy. Przed nim stawia się dwie rzeczy.

Pierwszą z nich jest starannie przygotowana wewnętrzna wiki: kanoniczne definicje, dokumentacja API, wzory na metryki oraz instrukcje obsługi, wszystko to przejrzane, zatwierdzone i kontrolowane pod kątem wersji. Gdy potrzebują oficjalnej odpowiedzi, szukają jej tam. To właśnie pełni rolę OKF.

Drugi to silnik wyszukiwania, który przewyższa wszystko inne: tysiące wiadomości w czacie, tematów e-maili, zgłoszeń obsługi klienta oraz transkrypcji spotkań. Gdy chcą dowiedzieć się, co ludzie mówili na dany temat, lub przeszukać nieuporządkowane archiwa, korzystają właśnie z niego. To jest RAG.

Żaden z nich sam w sobie nie jest wystarczający. Razem obejmują cały zakres wiedzy organizacji.

Czym jest OKF

OKF jest celowo prosty w strukturze. „Bundle” to katalog plików Markdown przechowywanych w Git. Każdy plik opisuje jeden koncept, taki jak tabela, wskaźnik, punkt końcowy API czy instrukcja postępowania, i zaczyna się od bloku YAML zawierającego metadane czytelne dla maszyn. Specyfikacja nie wymaga od twórców zbyt wiele, a narzędzia takie jak Obsidian, Notion czy MkDocs już obsługują tę samą strukturę plików. Projekt znajduje się w publicznym repozytorium.

Plik zawierający metrykę biznesową może mieć w swoim frontmatterze typ, tytuł, opis, właściciela, tagi oraz datę i godzinę utworzenia. W treści znajduje się następnie oficjalna formuła, kilka zasad (na przykład wykluczenie kont próbnych z mianownika oraz nieuwzględnianie obniżek planu jako odejść klientów), tabela stanowiąca źródło prawdy oraz linki do powiązanych koncepcji.

---
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)

Dlaczego marnować na to czas?

• Brak matematyki wektorowej. Gdy agent potrzebuje wzoru na odejścia klientów, odczytuje ten plik bezpośrednio. Nie ma żadnego embedowania, oceny podobieństwa ani mechanizmu top-k – zawsze dostępna jest tylko zatwierdzona odpowiedź.
• Integracja z standardowymi procesami Git. Zmiany przechodzą przez pull requests, przeglądy oraz historię commitów, dzięki czemu istnieje ślad audytowy pokazujący, kto, kiedy i dlaczego zmienił wzór.
• Brak konieczności utrzymywania infrastruktury. Nie ma potrzeby stosowania magazynów wektorowych, pipeline’ów do embedowania, strategii dzielenia na fragmenty ani zadań re-indexowania. Pliki znajdują się po prostu w folderze.

Czym jest RAG

RAG łączy model z dużymi, niestrukturyzowanymi danymi w sześciu krokach:

1. Przyjmowanie dokumentów takich jak pliki PDF, e-maile, strony wiki oraz wiadomości z czatów.
2. Dzielenie ich na mniejsze fragmenty.
3. Embedowanie każdego fragmentu jako wektora za pomocą modelu embedującego.
4. Przechowywanie wektorów w bazie danych takiej jak Pinecone, Weaviate lub pgvector.

W momencie wysyłania zapytania należy włączyć pytanie do tego samego kontekstu i pobrać najbardziej podobne fragmenty tekstu.

Należy dodać te fragmenty do promptu, aby model mógł odpowiedzieć z odpowiednim kontekstem.

Mocą RAG jest zasięg – potrafi wydobyć istotne materiały z tysięcy dokumentów, których nikt nie byłby w stanie zorganizować ręcznie. Jego słabością jest precyzja; ponieważ to podobieństwo kieruje procesem wyszukiwania, może zwrócić tekst powiązany z tematem, ale niekoniecznie autorytatywny. Jeśli trzy różne źródła definiują pojęcie „churn” nieco inaczej, RAG może wybrać niewłaściwe.

Projekt hybrydowy

W takiej architekturze przed obiema pamięciami umieszczony jest router. Router analizuje każde przychodzące zapytanie i decyduje, dokąd powinno trafić: do przygotowanej kolekcji, gdy pytanie dotyczy oficjalnej definicji, lub do wyszukiwania wektorowego, gdy jest otwarte i badawcze.

Społeczszczona wersja tego routera w Pythonie wykonywa cztery zadania. Ładuje wszystkie pliki Markdown z pakietu i indeksuje je według tytułu zawartego w frontmatter. Próbuje dopasować kluczowe słowa z zapytania do tych tytułów w sposób deterministyczny. Jeśli uda się tak znaleźć odpowiedni temat, treść jest przekazywana z oznaczeniem, że pochodzi z oficjalnej bazy wiedzy. W przeciwnym razie stosuje się wyszukiwanie wektorowe, oznaczone jako wyszukiwanie dokumentów, a następnie wybrany kontekst jest wysyłany do modelu z instrukcją, by odpowiadał wyłącznie na podstawie dostarczonej mu informacji. Oznaczenie źródła w instrukcji jest ważne, ponieważ informuje model, a później czytelnika, jak dużą wagę powinien mieć dany kontekst.

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

Porównanie tutaj jest celowo uproszczone – polega na wyszukiwaniu tytułów – aby idea pozostała widoczna. System produkcyjny wykorzystywałby lepsze metody kierowania ruchem, takie jak klasyfikator lub filtr metadanych, oraz radził sobie z sytuacją, gdy oba źródła zwracają coś istotnego.

Wniosek

Dla agentów korporacyjnych nie chodzi o wybór między OKF a RAG. Najlepszy projekt wykorzystuje oba podejścia. Deterministyczna baza wiedzy kontrolowana przez Git chroni fakty, które nigdy nie mogą być błędne: wskaźniki KPI, umowy API oraz procedury operacyjne. Probabilistyczne wyszukiwanie wektorowe obejmuje duże archiwa materiałów niestrukturyzowanych, których nikt nie może skatalogować. W rezultacie otrzymujemy agenta, który jest dokładny, gdy liczy się precyzja, oraz eksploracyjny, gdy ważne jest odkrywanie nowych informacji.