# 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 ``-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=`, `WEB_SEARCH_RESULT_COUNT=8`, `WEB_SEARCH_CONCURRENT_REQUESTS=4`, `WEB_FETCH_MAX_CONTENT_LENGTH=100000`, `USER_AGENT=` (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:`, `session_id:` (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:` 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).