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

13 KiB
Raw Blame History

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, DOC-Index, 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):

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