247 lines
9.1 KiB
Markdown
247 lines
9.1 KiB
Markdown
# Lokalna baza wiedzy
|
|
|
|
Ten katalog jest nowym magazynem wiedzy dla projektu `google ads ver 2`.
|
|
|
|
## Struktura katalogu
|
|
|
|
- `sources/` - surowe materialy do przetworzenia w kolejnych etapach.
|
|
- `rules.jsonl` - atomowe reguly wykorzystywane przez narzedzie.
|
|
- `imports.jsonl` - historia importow wiedzy.
|
|
- `lancedb/` - metadane indeksu semantycznego; fizyczne pliki LanceDB sa domyslnie w `%LOCALAPPDATA%\google-ads-ver2-knowledge-lancedb`.
|
|
|
|
`rules.jsonl` jest zrodlem prawdy. LanceDB jest tylko indeksem do wyszukiwania semantycznego i mozna go zawsze odbudowac z `rules.jsonl`.
|
|
|
|
Przenoszenie projektu na inny komputer:
|
|
|
|
- Przenosza sie: `knowledge/rules.jsonl`, `knowledge/sources/`, `knowledge/imports.jsonl` i dokumentacja.
|
|
- Nie musi przenosic sie: fizyczny katalog LanceDB z `%LOCALAPPDATA%`.
|
|
- Po przeniesieniu projektu uruchom:
|
|
|
|
```powershell
|
|
python -m pip install -r requirements.txt
|
|
python gads.py wiedza indeksuj
|
|
```
|
|
|
|
To odbuduje lokalny indeks LanceDB na nowym komputerze.
|
|
|
|
API modeli jest uzywane podczas:
|
|
|
|
- `wiedza dodaj` - ekstrakcja regul z materialu zrodlowego.
|
|
- `wiedza indeksuj` - utworzenie embeddingow aktywnych regul.
|
|
- `wiedza szukaj-ai` - embedding zapytania uzytkownika.
|
|
|
|
Analiza klienta Google Ads nie wywoluje API modeli.
|
|
|
|
## Komendy
|
|
|
|
Inicjalizacja katalogow i pustych plikow:
|
|
|
|
```powershell
|
|
python gads.py wiedza init
|
|
```
|
|
|
|
Test pliku bez kosztu API i bez zapisu regul:
|
|
|
|
```powershell
|
|
python gads.py wiedza dodaj --file "knowledge/sources/sample_lancedb_w055.md" --source "stara_lancedb_W055" --dry-run
|
|
```
|
|
|
|
Import przez API:
|
|
|
|
```powershell
|
|
python gads.py wiedza dodaj --file "knowledge/sources/sample_lancedb_w055.md" --source "stara_lancedb_W055"
|
|
```
|
|
|
|
Import calej starej bazy LanceDB bez API i bez przypisywania do zadan:
|
|
|
|
```powershell
|
|
python gads.py wiedza import-stare --from "D:\google ads\lancedb"
|
|
```
|
|
|
|
Ten import:
|
|
|
|
- czyta tabele `fakty`,
|
|
- przenosi kazdy rekord jako aktywna regule,
|
|
- zostawia `task_ids` i `suggested_task_ids` puste,
|
|
- pomija rekordy, ktore juz istnieja po `id`,
|
|
- po imporcie wymaga odswiezenia indeksu przez `python gads.py wiedza indeksuj`.
|
|
|
|
Po imporcie skrypt pokazuje propozycje przypisania regul do zadan i pyta o kazda z nich:
|
|
|
|
```text
|
|
Dodac regule <id_reguly> do zadania <task_id>?
|
|
```
|
|
|
|
Odpowiedzi:
|
|
|
|
- `TAK` - dopisuje `task_id` do reguly.
|
|
- `NIE` - odrzuca propozycje.
|
|
- Enter - zostawia propozycje jako oczekujaca do pozniejszej decyzji.
|
|
|
|
Lista oczekujacych propozycji:
|
|
|
|
```powershell
|
|
python gads.py wiedza propozycje
|
|
```
|
|
|
|
Wznawialny przeglad regul bez przypisan do zadan:
|
|
|
|
```powershell
|
|
python gads.py wiedza przypisz
|
|
```
|
|
|
|
Komenda przechodzi po aktywnych regulach, ktore maja puste `task_ids`, w kolejnosci zapisanej w `knowledge/rules.jsonl`. To celowe: uzytkownik moze latwo porownac przeglad z otwartym plikiem i z kolejnoscia importu. Skrypt pokazuje liste aktualnych zadan i pyta, do ktorego zadania dodac regule. Mozna wpisac:
|
|
|
|
- numer zadania, np. `2`,
|
|
- kilka numerow po przecinku, np. `2,4`,
|
|
- techniczny `task_id`, np. `check_pla_settings`,
|
|
- `P`, aby pominac regule i przejsc dalej,
|
|
- `U`, aby trwale usunac regule z `knowledge/rules.jsonl`,
|
|
- `Q`, aby przerwac bez przesuwania kursora.
|
|
|
|
Domyslnie komenda pokazuje jedna regule, pyta o decyzje i konczy porcje. To jest preferowany tryb pracy, bo agent i uzytkownik moga ocenic pelny kontekst bez pospiechu. Wieksza porcje wlaczaj tylko swiadomie, np.:
|
|
|
|
```powershell
|
|
python gads.py wiedza przypisz --limit 10
|
|
```
|
|
|
|
Usuwanie przez `U` wymaga dodatkowego potwierdzenia tekstem `USUN`. Po potwierdzeniu rekord jest fizycznie usuwany z `rules.jsonl`, a postep przegladu jest zapisywany tak, zeby kolejne uruchomienie zaczelo od nastepnej reguly. Po usunieciach uruchom `python gads.py wiedza indeksuj`, zeby LanceDB nie zawierala starych rekordow. Tej opcji uzywaj dla ewidentnie blednych, pustych albo bezuzytecznych rekordow z importu. Jesli regula jest poprawna, ale nie ma byc uzywana teraz, lepiej wpisac `P` albo oznaczyc ja poza przegladem jako `archived`.
|
|
|
|
Postep jest zapisywany w `knowledge/review_state.json`. Aby zaczac od poczatku:
|
|
|
|
```powershell
|
|
python gads.py wiedza przypisz --restart
|
|
```
|
|
|
|
Po dodaniu nowych zadan do `config/tasks.toml` uruchom ponownie `python gads.py wiedza przypisz --restart`, zeby przejrzec nieprzypisane reguly pod katem nowych zadan.
|
|
|
|
Reczna akceptacja pojedynczej propozycji:
|
|
|
|
```powershell
|
|
python gads.py wiedza zatwierdz --rule-id "<id_reguly>" --task "<task_id>"
|
|
```
|
|
|
|
Reczne odrzucenie pojedynczej propozycji:
|
|
|
|
```powershell
|
|
python gads.py wiedza odrzuc --rule-id "<id_reguly>" --task "<task_id>"
|
|
```
|
|
|
|
Wyszukiwanie tekstowe po zapisanych regulach:
|
|
|
|
```powershell
|
|
python gads.py wiedza szukaj "pmax display remarketing"
|
|
```
|
|
|
|
Budowa indeksu semantycznego LanceDB:
|
|
|
|
```powershell
|
|
python gads.py wiedza indeksuj
|
|
```
|
|
|
|
Domyslnie fizyczny indeks LanceDB jest poza katalogiem projektu, bo na Windows katalogi synchronizowane potrafia blokowac operacje zapisu wymagane przez LanceDB. Sciezke mozna nadpisac zmienna:
|
|
|
|
```text
|
|
KNOWLEDGE_LANCEDB_DIR=C:\sciezka\do\lokalnego\lancedb
|
|
```
|
|
|
|
Wyszukiwanie semantyczne:
|
|
|
|
```powershell
|
|
python gads.py wiedza szukaj-ai "czy PMax kanibalizuje kampanie Display?"
|
|
```
|
|
|
|
Lista regul z filtrami:
|
|
|
|
```powershell
|
|
python gads.py wiedza lista
|
|
python gads.py wiedza lista --topic shopping
|
|
python gads.py wiedza lista --task check_pla_settings
|
|
python gads.py wiedza lista --status archived
|
|
python gads.py wiedza lista --source "stara_lancedb"
|
|
```
|
|
|
|
Statystyki bazy:
|
|
|
|
```powershell
|
|
python gads.py wiedza statystyki
|
|
```
|
|
|
|
Statusy regul:
|
|
|
|
```powershell
|
|
python gads.py wiedza archiwizuj --rule-id "<id_reguly>"
|
|
python gads.py wiedza aktywuj --rule-id "<id_reguly>"
|
|
python gads.py wiedza duplikat --rule-id "<id_reguly>" --duplicate-of "<id_reguly_nadrzednej>"
|
|
```
|
|
|
|
Lista regul przypisanych do zadania:
|
|
|
|
```powershell
|
|
python gads.py wiedza reguly --task check_pla_settings
|
|
```
|
|
|
|
## Konfiguracja API
|
|
|
|
Do importu przez API potrzebny jest klucz w `.env`:
|
|
|
|
```text
|
|
OPENAI_API_KEY=...
|
|
```
|
|
|
|
Opcjonalnie mozna ustawic model:
|
|
|
|
```text
|
|
KNOWLEDGE_OPENAI_MODEL=gpt-4.1-mini
|
|
KNOWLEDGE_EMBEDDING_MODEL=text-embedding-3-small
|
|
KNOWLEDGE_LANCEDB_DIR=C:\opcjonalna\sciezka\poza\synchronizacja
|
|
```
|
|
|
|
Mozna tez podac model jednorazowo:
|
|
|
|
```powershell
|
|
python gads.py wiedza dodaj --file "knowledge/sources/sample_lancedb_w055.md" --source "stara_lancedb_W055" --model gpt-4.1-mini
|
|
```
|
|
|
|
## Schemat reguly
|
|
|
|
Kazdy wiersz `rules.jsonl` jest osobnym obiektem JSON. Wymagane pola:
|
|
|
|
- `id` - stabilny identyfikator reguly, bez spacji.
|
|
- `status` - `active`, `draft`, `archived` albo `duplicate`.
|
|
- `topic` - krotki temat, np. `search`, `pmax`, `shopping`, `konwersje`, `gtm-tracking`.
|
|
- `task_ids` - lista zadan zaakceptowanych przez uzytkownika; importer nie powinien dopisywac ich bez akceptacji.
|
|
- `suggested_task_ids` - propozycje zadan do akceptacji; skrypt pokazuje je uzytkownikowi po imporcie.
|
|
- `rule_type` - `audit_check`, `recommendation`, `warning` albo `implementation_note`.
|
|
- `condition` - kiedy regula ma znaczenie.
|
|
- `recommendation` - co agent albo narzedzie powinno zrobic.
|
|
- `risk` - jakie ryzyko ogranicza regula.
|
|
- `source` - czytelna nazwa zrodla podana w `--source`.
|
|
- `source_file` - plik zrodlowy, z ktorego powstala regula.
|
|
- `confidence` - `low`, `medium` albo `high`.
|
|
- `created_at` - data utworzenia reguly.
|
|
- `updated_at` - data ostatniej zmiany metadanych, statusu lub przypisan.
|
|
- `duplicate_of` - ID reguly nadrzednej, gdy `status` ma wartosc `duplicate`.
|
|
- `supersedes` - lista ID regul zastapionych przez te regule.
|
|
- `text` - jednozdaniowa wersja reguly do wyszukiwania i wyswietlania.
|
|
|
|
Przykladowy rekord `rules.jsonl`:
|
|
|
|
```json
|
|
{"id":"search_partners_quality_check","status":"active","topic":"search","task_ids":[],"suggested_task_ids":["check_search_settings"],"rule_type":"audit_check","condition":"Kampania Search ma wlaczona siec partnerska Google","recommendation":"Sprawdz wyniki Search Partners osobno przed rekomendacja pozostawienia tej opcji.","risk":"Mozliwy ruch niskiej jakosci lub zawyzone konwersje.","source":"manual","source_file":"knowledge/sources/search.md","confidence":"medium","created_at":"2026-05-14T18:00:00","updated_at":"2026-05-14T18:00:00","duplicate_of":"","supersedes":[],"text":"Search Partners sprawdzaj osobno przy problemach z jakoscia ruchu."}
|
|
```
|
|
|
|
## Zasady dla agentow AI
|
|
|
|
- Nie wpisuj recznie duzych pakietow regul do `rules.jsonl`, jesli material moze przejsc przez `wiedza dodaj`.
|
|
- Przed importem wrzuc material do `knowledge/sources/` albo wskaz istniejacy plik.
|
|
- Najpierw uruchom `--dry-run`, zeby sprawdzic sciezke, zrodlo i model bez kosztu API.
|
|
- Po imporcie sprawdz wynik przez `python gads.py wiedza szukaj "<temat>"`.
|
|
- Nie dopisuj `task_ids` recznie po imporcie. Uzyj pytan skryptu albo komendy `wiedza zatwierdz`.
|
|
- Nie usuwaj historycznych regul recznie. Uzyj `wiedza archiwizuj` albo `wiedza duplikat`, zeby zachowac slady decyzji.
|
|
- Po wiekszych zmianach w `rules.jsonl` uruchom `python gads.py wiedza indeksuj`, zeby odswiezyc LanceDB.
|
|
- Nie edytuj plikow LanceDB recznie. To indeks, nie zrodlo prawdy.
|
|
- Reguly w `rules.jsonl` maja wspierac plany i checklisty. Nie sa zgoda na wdrozenie zmian na koncie Google Ads.
|
|
- Jesli regula dotyczy przyszlego zadania, zostaw `task_ids` i `suggested_task_ids` puste, a pozniej dopisz zadanie w `config/tasks.toml`.
|
|
- Nie zapisuj kluczy API w tym katalogu. Klucze trzymamy w `.env`.
|