Files
infrastructure/docs/platform/llm-server/ai/GNAI-020-TECH_OpenWebUI-WebSearch.md
T
vibe-agent 49de44e77b
ci-static / secret-scan (push) Successful in 21s
ci-static / yamllint (push) Successful in 34s
ci-static / ansible-syntax (push) Successful in 30s
ci-static / markdown-links (push) Successful in 22s
M6: Websuche produktiv (SearXNG kuratiert + Native/Agentic Mode) — GNAI-020 (#16)
Co-authored-by: vibe-agent <vibe-agent@ghostnet.local>
2026-11-12 20:53:38 +01:00

201 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Technischer Arbeitsentwurf
**Dokumenten-ID:** GNAI-020-TECH
**Titel:** Websuche in OpenWebUI (SearXNG, self-hosted) — kuratierte Engines + Native/Agentic Mode
**Stand:** 2026-11-12
**Status:** produktiv und E2E-verifiziert (Abschnitt 4), vom Betreiber im UI bestätigt (12.11.2026); Betreiber-Entscheidung 2026-11-12: Option A (self-hosted SearXNG, kein externer API-Key)
**Referenzen:** [Roadmap M6](../../../GNAI-001-PLAN_Project-Roadmap.md), [DOC-Index](../../../GNAI-000-DOC_Index.md), Rollen `llm-server/llm/ansible/roles/web_search/` und `roles/open_webui/` (READMEs), OpenWebUI-Doku Stand 2026-11-10 (docs.openwebui.com)
> Dieses Dokument beschreibt den technischen Sollzustand und den belegten
> Betriebsstand der Websuche in OpenWebUI.
---
## Änderungsverlauf
| Datum | Version | Autor | Beschreibung |
| --- | --- | --- | --- |
| 2026-11-12 | 0.1 | spektr / Mistral Vibe | Erstfassung: Befunde, Umsetzung (Rollen `web_search`/`open_webui`), Verifikation, Betriebs-Pfade |
| 2026-11-12 | 0.2 | spektr / Mistral Vibe | Befund h) ergänzt: `meta.defaultFeatureIds` war leer — neue UI-Chats starteten ohne Web-Search-Toggle; Model-Sync setzt jetzt `defaultFeatureIds=["web_search"]`; E2E-Nachweis nur mit Builtin-Tools; NPM-Timeout-Schritt (Abschnitt 6) durch Betreiber ausgeführt und als erledigt markiert |
---
## 1. Entscheidung
Betreiberentscheid 2026-11-12: Agenten und Nutzer von `https://chat.ghostnet.selfhost.eu`
sollen harness-grade Websuche bekommen (mehrstufiger search→fetch→search-Loop mit
zitierbaren Quellen), self-hosted über die bestehende SearXNG-Instanz im
Egress-Netz — **kein externer Search-API-Key** (Option A aus der Recherche vom
2026-11-11; externe Anbieter Exa/Tavily/Brave bleiben als Erweiterung offen, Abschnitt 7).
Recherche-Ergebnis (November 2026): OpenWebUI v0.13.3 (neuestes Release, 2026-11-08)
bietet zwei Modi — Legacy-RAG (unsupported) und **Native/Agentic Mode** (Default seit
v0.10) mit den Builtin-Tools `search_web` (Snippets, kein RAG/Embedding) und
`fetch_url` (ganze Seite, zitierfähig). Harnesses (Claude Code, OpenCode, LM Studio
Bionic) arbeiten prinzipiell gleich: das Modell entscheidet selbst, wann es sucht und
liest. Externe APIs (Benchmark openbenchmarks 2026-10-21): Exa 99,3 % / Tavily 97,7 %
Accuracy — SearXNG ist qualitativ von den Upstream-Engines abhängig, bleibt aber die
Privacy-konforme Wahl.
## 2. Befunde: warum die bisherige Implementierung nicht funktionierte
a) **`ENABLE_WEB_SEARCH` fehlte** — in v0.13.3 ist der Default **False**
(`config.py:1169`). Ohne dieses Gate werden `search_web`/`fetch_url` nie injiziert.
b) **Persistierte Config schlägt Env** — OpenWebUI legt jeden ConfigVar in der
`config`-Tabelle ab und die DB gewinnt über die Env-Variable. Die DB enthielt
`web.search.enable=false`, `web.search.engine=""`, `web.search.searxng_query_url=""`
(Seeding beim ersten Start) — die Env-Werte der Rolle griffen faktisch nicht.
c) **`ENABLE_RAG_WEB_SEARCH=True` war in v0.13.3 eine tote Variable** — der
Legacy-RAG-Pfad existiert nicht mehr; ein Embedding-Download beim ersten
Suchlauf (SentenceTransformers all-MiniLM-L6-v2, ~500 MB) war ein Hänge-Kandidat.
d) **SearXNG lief mit allen 123 Default-Engines** (`use_default_settings: true`),
inkl. key-loser API-Engines und Warez-/Adult-Indizes — langsam, CAPTCHA/429-Bans
bis 15 Tage (`suspended_times`).
e) **API vs. UI**: Builtin-Tools werden nur für UI-Requests (mit `session_id`)
injiziert (`utils/middleware.py:2070`); reine API-Requests ohne `chat_id`+`id`
bekommen rohe `tool_calls` zurück (Client-seitige Ausführung). Server-seitiger
Tool-Loop für API-Agenten: **Path A** (Abschnitt 5).
f) `SEARXNG_QUERY_URL` mit `<query>`-Placeholder ist korrekt: v0.13.3 streicht den
Query-String und sendet `q`/`format=json` selbst (`retrieval/web/searxng.py`).
SearXNG braucht `search.formats: [html, json]` (sonst 403).
g) SearXNG durchsucht ohne `categories`-Parameter nur die Kategorie `general`
(`webadapter.py get_selected_categories`) — IT-/Science-/News-Engines wären ohne
Override nie angesprungen.
h) **Neuer Chat ohne Web-Search-Toggle**: `meta.defaultFeatureIds` des Modells war
leer — in v0.13.3 startet ein neuer UI-Chat mit `webSearchEnabled` nur dann, wenn
`defaultFeatureIds` `"web_search"` enthält (`Chat.svelte defaultFeature()`).
Behebung: Model-Sync setzt `defaultFeatureIds=["web_search"]` (verifiziert per
`/api/models`: `info.meta.defaultFeatureIds = ['web_search']`).
## 3. Umsetzung (Ansible, Playbook `webui.yml`, Inventory `production`)
### 3.1 Rolle `web_search` (SearXNG)
- `templates/settings.yml.j2`: `use_default_settings.engines.keep_only` mit 43
kuratierten Engines (Web: bing, brave, duckduckgo, startpage, mojeek, qwant,
swisscows, mwmbl, marginalia; News: bing/brave./ddg/mojeek/startpage/swisscows/yahoo
news, reuters, tagesschau; Wikis: wikipedia, wikidata; IT/Doku: github,
github code, gitlab, stackoverflow, askubuntu, superuser, arch linux wiki, pypi,
npm, crates.io, repology, docker hub, microsoft learn, mdn, hackernews; Science/
Security: arxiv, semantic scholar, pubmed, europepmc, openalex, crossref,
springer nature, national vulnerability database). Engine-Namen exakt wie in der
Default-`settings.yml` des gepinnten Images (Commit `626105eec`). Jeder Engine per
`engines:`-Override auf `disabled: false` + `categories: [general]` (siehe 2g).
- `outgoing.request_timeout: 2.5`, `max_request_timeout: 8` (Default 3.0/10.0);
`search.suspended_times` auf 60–600 s verkürzt (Datacenter-Egress landet sonst
tagelang auf Bans); `limiter: false`, `formats: [html, json]` wie gehabt.
- Playbook-Probe verschärft: JSON-API muss echte `results` liefern (nicht nur HTTP 200).
### 3.2 Rolle `open_webui`
- Env (Quadlet): `ENABLE_WEB_SEARCH=True`, `WEB_SEARCH_ENGINE=searxng`,
`SEARXNG_QUERY_URL=http://searxng:8080/search?q=<query>`, `WEB_SEARCH_RESULT_COUNT=8`,
`WEB_SEARCH_CONCURRENT_REQUESTS=4`, `WEB_FETCH_MAX_CONTENT_LENGTH=100000`,
`USER_AGENT=<realistischer Browser-String>` (Bot-Detection des Web-Loaders);
`ENABLE_RAG_WEB_SEARCH` entfernt (2c).
- Quadlet-Template: `Environment="KEY=value"` quoting (sonst splittet systemd Werte
mit Leerzeichen — betraf u. a. `OAUTH_SCOPES=openid email profile`).
- DB-Sync (idempotent, sqlite wie beim Model-Sync):
- `config`-Zeilen `web.search.enable=true`, `web.search.engine="searxng"`,
`web.search.searxng_query_url`, `web.search.result_count=8`,
`web.search.concurrent_requests=4`, `web.fetch.max_content_length=100000`
(korrigiert 2b; Config wird pro Request aus der DB gelesen, kein Restart nötig).
- Model-Row `swift-1.5-qwen3.8-27b-q6k`: `meta.capabilities.web_search=true`,
`meta.builtinTools.web_search=true` und `meta.defaultFeatureIds=["web_search"]`
(Defaults sind true, aber explizit — ein UI-Toggle darf API-Agenten nicht
unbemerkt kappen; `defaultFeatureIds` schaltet den Web-Search-Toggle in neuen
UI-Chats default an, siehe 2h). Native Function Calling ist seit v0.10 Default,
`params` bleibt `{}`.
- Workspace-Tool **`gnai-web-search`** (`files/gnai-web-search-tool.py` +
`files/gnai-web-search-tool.specs.json`): `web_search(query, count, time_range)`
und `fetch_url(url)` gegen `http://searxng:8080` (aiohttp, Browser-UA, 100k-Cap),
mit public read `access_grant` für alle User. Für API-Agenten, die per
`tool_ids` explizit Tools anfordern (2e).
## 4. Verifikation (2026-11-12, produktiv auf `10.0.0.90`)
a) Playbook: `--check --diff` sauber, produktiver Lauf ok, danach **`changed=0`**
(Idempotenz, GNAI-010 10.4).
b) SearXNG in-container: 168 Ergebnisse in **1,36 s** (vorher: 123 Engines, bis 10 s+).
c) Aus dem OpenWebUI-Container via Alias `searxng`: HTTP 200, JSON mit Ergebnissen
in **1,9 s**.
d) OpenWebUI-Container-Env enthält alle Web-Search-Variablen; Health `HTTP 200`;
Model-Row-Meta und `config`-Zeilen korrekt in `webui.db`.
e) **E2E-Tool-Loop (Path A, Abschnitt 5)**: Chat via API mit `features.web_search=true`
+ `session_id` + `tool_ids=["gnai-web-search"]` — das Modell führte mehrere
`web_search`/`fetch_url`-Runden server-seitig aus (sah widersprüchliche Angaben
v0.12.5 vs v0.13.0, verifizierte per GitHub-API) und antwortete mit Quellen:
„aktuellste Release **v0.13.3** vom 2026-11-08“ — korrekt (Cross-Check gegen
`api.github.com/repos/open-webui/open-webui/releases/latest`).
f) **E2E nur mit Builtin-Tools** (kein `tool_ids`, nur `session_id` +
`features.web_search=true`): Chat-Record zeigt `function_call search_web` ×2 mit
echten SearXNG-Ergebnis-JSONs, dann `function_call fetch_url` ×2 mit Seiteninhalt,
`sources` enthält die gelesene GitHub-Releases-Seite (Zitation), finale Antwort
korrekt mit 3 Quellen. Damit ist der UI-Pfad (neuer Chat, Toggle via
`defaultFeatureIds` an) abgedeckt.
g) Nach beiden Tests: Playbook-Lauf `changed=0`; Test-Chats gelöscht, temporärer
Test-API-Key entfernt, `auth.enable_api_keys` wieder auf `false`.
h) **Betreiber-Bestätigung im UI (12.11.2026):** neuer Chat auf frisch geladener
Seite — Web-Search-Toggle default an (über `defaultFeatureIds`), das Modell
sieht `search_web`/`fetch_url` und nutzt sie im Research-Loop.
## 5. Betrieb: Websuche in UI und API
- **UI (Browser, OIDC)**: Web-Search-Toggle im Chat (oder Default-Feature am Modell) →
`search_web`/`fetch_url` als Native-Tools; Zitationen erscheinen, sobald das Modell
eine Seite per `fetch_url` gelesen hat.
- **API-Agenten — Path A (empfohlen, voller agentic Loop server-seitig)**:
1. `POST /api/v1/chats/new` (Chat mit User- + leerer Assistant-Message anlegen) → `chat_id`.
2. `POST /api/chat/completions` mit `stream:true`, `chat_id`, `id:<assistant-msg-id>`,
`session_id:<beliebig non-empty>` (schaltet Builtin-Tools frei), `features:{web_search:true}`,
optional `tool_ids:["gnai-web-search"]` → Antwort `{"status":true,"task_ids":[...]}`.
3. Ergebnis aus dem Chat lesen: `GET /api/v1/chats/{chat_id}` (Poll bis `done:true`).
Ohne `chat_id`+`id`+`stream` werden rohe `tool_calls` an den Client zurückgegeben
(Client-seitige Ausführung, OpenAI-Semantik) — siehe docs.openwebui.com
„Server-Side Tool Calling (API)".
Kompakt als curl (API-Key des Users vorausgesetzt; `auth.enable_api_keys` muss
global an sein — aktuell `false`, siehe Abschnitt 7):
```bash
# A1: Chat anlegen (User- + leere Assistant-Message)
CHAT_ID=$(curl -s -X POST "$OWUI_URL/api/v1/chats/new" -H "Authorization: Bearer $OWUI_KEY" \
-H "Content-Type: application/json" -d "{\"chat\":{\"title\":\"run\",\"models\":[\"$MODEL\"],\"history\":{\"currentId\":\"$AID\",\"messages\":{\"$UID\":{\"id\":\"$UID\",\"role\":\"user\",\"content\":\"...\",\"timestamp\":$TS,\"models\":[\"$MODEL\"],\"childrenIds\":[\"$AID\"]},\"$AID\":{\"id\":\"$AID\",\"role\":\"assistant\",\"content\":\"\",\"parentId\":\"$UID\",\"childrenIds\":[],\"model\":\"$MODEL\",\"modelIdx\":0,\"done\":false,\"timestamp\":$((TS+1))}}}}}" | jq -r .id)
# A2: Completion feuern — server-seitiger Tool-Loop (stream:true + chat_id + id + session_id)
curl -s -X POST "$OWUI_URL/api/chat/completions" -H "Authorization: Bearer $OWUI_KEY" \
-H "Content-Type: application/json" -d "{\"model\":\"$MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"Recherchiere ...\"}],\"stream\":true,\"chat_id\":\"$CHAT_ID\",\"id\":\"$AID\",\"session_id\":\"api-$(uuidgen)\",\"features\":{\"web_search\":true}}"
# -> {"status":true,"task_ids":[...],"chat_id":"..."}
# A3: Ergebnis pollen
curl -s "$OWUI_URL/api/v1/chats/$CHAT_ID" -H "Authorization: Bearer $OWUI_KEY" | jq ".chat.history.messages[\"$AID\"] | {done, content, sources}"
```
- **Path B** (`params.function_calling:"legacy"` + `tool_ids`): eine Tool-Runde vor
der Antwort, Antwort im HTTP-Body — ohne Builtin-Tools.
## 6. NPM-Proxy-Timeout (CT 103) — erledigt 2026-11-12
Lange Research-Loops (mehrere Tool-Runden, 128k-Kontext, xhigh) dauern Minuten —
der NPM-Default-`proxy_read_timeout` (60 s) schneidet den Stream ab. **Durch den
Betreiber am 12.11.2026 ausgeführt:** NPM → Proxy Hosts → `chat.ghostnet.selfhost.eu`
→ Edit → Advanced → Custom Nginx: `proxy_read_timeout 600s; proxy_send_timeout 600s;
proxy_connect_timeout 60s;` (Websocket-Support war bereits aktiv). Konfiguriert
in der NPM-Datenbank auf CT 103, nicht im Repository.
## 7. Offene Punkte / Erweiterungen
- `auth.enable_api_keys` steht auf `false` (Default) — API-Keys für Agenten müssen
global und pro User freigegeben werden, wenn Agenten Path A nutzen sollen
(Betreiber-Entscheidung offen; UI-Verifikation ist auch ohne API-Key möglich).
- Optional externer Key (Tavily/Exa/Brave als Podman-Secret + `WEB_SEARCH_ENGINE`),
falls SearXNG-Qualität für News nicht reicht (Benchmark: Exa/Tavily ~97–99 %).
- Optional MCP: SearXNG-MCP-Container im Egress-Netz als `server:mcp:<id>` in
OpenWebUI registrieren (native MCP-Unterstützung seit v0.6.31, Streamable HTTP).
- Optional v0.13 „Open Terminal“ (realer Browser/Desktop für das Modell) für
JS-lastige Seiten — zusätzlicher Dienst, Egress nötig.
- `ENABLE_WEB_SEARCH_CONFIRMATION=True` möglich (User bestätigt jede Suche) — für
die interne SearXNG-Instanz nicht gesetzt.
- Tool-Loop-Verhalten des Modells bei xhigh/128k überwachen (GPU-Last bei langen
Recherchen; ggf. `WEB_SEARCH_RESULT_COUNT` oder `WEB_FETCH_MAX_CONTENT_LENGTH` senken).