Atgal į žurnalą
•4 min. skaitymo

Pragmatiškas RAG: Google Open Knowledge Format (OKF) bandymas

Vien tik vektorių paieška neišsprendžia konteksto surinkimo problemos DI agentams. Štai kaip aš struktūrizavau repozitorijos dokumentaciją kaip naršomą markdown grafiką naudodamas OKF specifikaciją.

Google CloudAI AgentsRAGMarkdownOKFDocumentation
Pragmatiškas RAG: Google Open Knowledge Format (OKF) bandymas

Jei integravote DI agentus į realią kodo bazę, tikriausiai susidūrėte su paprastos vektorių paieškos ribomis.

Paprašote agento refaktūrizuoti API galutinį tašką, ir jis nuskaito funkcijos kūną naudodamas vektorių paiešką. Tačiau jam trūksta duomenų bazės schemos, autentifikavimo tarpinės programinės įrangos ir diegimo instrukcijų, nes jie neturėjo pakankamai semantinio sutapimo.

Agentas patiria nesėkmę, nes veikia konteksto vakuume.

Siekdama išspręsti šią „konteksto surinkimo“ problemą, „Google Cloud“ paskelbė Open Knowledge Format (OKF) specifikaciją. Tai nepriklausomas standartas, skirtas paversti tekstinių failų katalogą semantiniu žinių grafu, kurį DI agentai gali naršyti rekursyviai.

Štai mano praktinė patirtis su jo įgyvendinimu.

Realus diegimas: OKF šiame portfolio

Vietoj to, kad tiesiog aiškinčiau koncepciją, aš įdiegiau OKF visoje šio portfolio dokumentacijoje. Galite tyrinėti tikrąją žinių bazę šios repozitorijos /knowledge/ kataloge.

OKF formalizuoja tai, ką daugelis platformų komandų jau darė: vidinės dokumentacijos struktūrizavimą kaip švarų katalogų medį iš paprastų Markdown failų su YAML frontmatter.

Vietoj patentuotų grafikų duomenų bazių ar sudėtingų vektorių indeksavimo vamzdynų įvedimo, OKF remiasi dviem žiniatinklio standartais:

  1. YAML Frontmatter failų lygio metaduomenims (deklaruoti, kas yra failas).
  2. Standartinės Markdown nuorodos ryšiams tarp failų deklaruoti (nurodyti agentui kitą mazgą).

Susiedami failus tiesiogiai tekste, paverčiate dokumentacijos katalogą žinių grafiku. Bet kuris LLM agentas, analizuojantis failą, gali sekti šias nuorodas lygiai taip pat, kaip interneto paieškos robotas naršo HTML inkarus.

Faktinis įgyvendinimas šiame portfolio

Šis portfolio įgyvendina OKF kataloge /knowledge/. Štai tikroji struktūra:

TEXT
/knowledge/
  ├── index.md                    <-- Entry point with type: "index"
  ├── architecture/
  │   └── directory-layout.md     <-- Architecture documentation
  ├── guidelines/
  │   ├── journal-publishing.md   <-- Blog publishing guidelines
  │   ├── cover-art.md            <-- Cover art guidelines
  │   └── ...                     <-- Additional guidelines

Kiekvienas failas prasideda tinkamu OKF frontmatter. Štai tikroji YAML antraštė iš /knowledge/index.md:

YAML
---
type: "index"
title: "dds.com Codebase Knowledge Base"
description: "Entry point for Google OKF-compliant repository knowledge graph describing layout and journal workflows."
timestamp: "2026-07-06T13:10:00Z"
tags: ["OKF", "documentation", "architecture", "guidelines"]
---

Turinys apima aiškius ryšius tarp dokumentų. Pavyzdžiui, journal-publishing.md rasite:

MARKDOWN
For information on creating cover art for your posts, see the [Cover Art Guidelines](./cover-art.md). For an overview of the entire codebase architecture, refer to the [Directory Layout](../architecture/directory-layout.md).

Tai sukuria naršomą grafiką, kurį tiek žmonės, tiek DI agentai gali efektyviai naršyti.

Kaip agentai naršo šį tikrąjį grafiką

Tradicinis RAG ieško raktinių žodžių ar semantinių vektorių, paimdamas 5 geriausias ištraukas ir patalpindamas jas į promptą.

OKF įgalina naršymo RAG strategiją:

  1. Įvesties taško pasirinkimas: Agentas atlieka lengvą vektorių paiešką arba užklausą pagal raktinius žodžius, kad surastų pradinį atitinkamą dokumentą (pvz., journal-publishing.md).
  2. Rekursinis analizavimas: Agentas analizuoja dokumentą, nuskaito YAML antraštę, kad identifikuotų dokumento tipą, ir ištraukia visas santykines nuorodas.
  3. Konteksto surinkimas: Priklausomai nuo užduoties, agentas rekursiškai įkelia susijusius failus, kad sukurtų pilną kontekstą.

Pavyzdžiui, jei agentui reikėtų suprasti, kaip šiame portfolio yra tikrinami tinklaraščio įrašai, jis galėtų:

  1. Pradėti nuo journal-publishing.md (rasto per paiešką)
  2. Sekti nuorodą į ../architecture/directory-layout.md, kad suprastų kodo bazės struktūrą
  3. Atrasti tikrinimo scenarijus architektūros dokumentacijoje
  4. Įkelti susijusias gaires, tokias kaip blog-validation-tools.md, dėl įgyvendinimo detalių

Tai pašalina konteksto lango perpildymą, nes agentas ištraukia tik tuos failus, kurie yra aiškiai svarbūs, visiškai aplenkdamas bendros paieškos triukšmą.

Automatizuotas tikrinimas

Norėdami užtikrinti, kad OKF struktūra išliktų nepažeista, aš įdiegiau automatinį tikrinimą:

  • Scenarijus patikrina, ar visi markdown failai turi tinkamą frontmatter antraštę
  • Patikrina privalomus laukus (type, title, description, timestamp)
  • Užtikrina, kad indekso failas egzistuotų su tipu type: "index"
  • Įspėja apie failus be santykinių nuorodų (potencialius atjungtus mazgus)

Šis tikrinimas automatiškai paleidžiamas kūrimo proceso metu, užkertant kelią sugadintos ar netinkamos formos dokumentacijos diegimui.

Realūs rezultatai: ar OKF to vertas?

Įdiegus OKF šioje tikroje kodo bazėje, štai mano sąžiningas įvertinimas, pagrįstas realia patirtimi:

Privalumai:

  • Jokio priklausymo tiekėjui: Tai tik Markdown. Galite peržiūrėti jį VS Code, talpinti GitHub arba indeksuoti naudojant bet kurį LLM teikėją.
  • Git suderinamas versijų kūrimas: Dokumentacijos atnaujinimai vyksta per standartines Pull Request ir sujungimo peržiūras.
  • Agento nepriklausomybė: Agentams nereikia pasirinktinių duomenų bazių tvarkyklių; jiems tereikia markdown analizatoriaus.
  • Kūrėjo patirtis: Inžinieriai gali naršyti dokumentaciją taip pat, kaip naršo kodą – sekdami aiškias nuorodas.

Išspręsti iššūkiai:

  • Nuorodų pasenimas: Mūsų automatizuotas tikrinimas randa sugedusias nuorodas kūrimo proceso metu.
  • Priežiūros išlaidos: Tikrinimo scenarijai užtikrina, kad nauja dokumentacija automatiškai atitiktų OKF taisykles.

Praktikoje OKF padarė šio portfolio dokumentaciją daug lengviau naršomą tiek žmonėms, tiek DI agentams. Kai užduodu klausimus apie kodo bazės struktūrą, agentai dabar gali sekti aiškias nuorodas, kad sukurtų pilną kontekstą, užuot spėlioję, kurie dokumentai gali būti naudingi.

OKF yra pragmatiškas požiūris į konteksto surinkimą. Jei kovojate su haliucinacijomis ar nepilnu agento kontekstu, jūsų repozitorijos /docs arba /knowledge katalogo struktūrizavimas pagal OKF yra nebrangus ir labai efektyvus architektūrinis sprendimas.

Share this article