Ricerca del portale: Typesense + "Chiedi all'AI" (RAG)

Il portale usa Typesense self-hosted per la ricerca (esperienza "Algolia-like": tipo-tolleranza, risultati raggruppati per pagina, evidenziazione) e la Conversational Search di Typesense per la funzione ✨ Chiedi all'AI (RAG con OpenAI).

Se il backend di ricerca non e' configurato, il portale ricade automaticamente sulla ricerca lunr integrata di DocFX: la build funziona comunque.

Important

Tutto resta interno. L'indice contiene l'intera documentazione (incluse analisi di sicurezza) e per questo Typesense e' self-hosted, non su Typesense Cloud. La chiave OpenAI vive solo nel server Typesense (server-side): non finisce mai nel browser. Nel sito statico va solo una chiave Typesense search-only a scope ridotto.

Come sono fatti i pezzi

Pezzo	Dove	Ruolo
Server Typesense	`docs-site/search/docker-compose.yml`	motore di ricerca + Conversational Search
`bootstrap.py`	`docs-site/search/`	crea collection, chiave search-only, modello RAG; scrive la config frontend
`index.py`	`docs-site/search/`	parsea `_site/**` e popola l'indice (record in stile DocSearch)
`main.js` + `main.css`	`docs-site/templates/infocad/public/`	barra di ricerca unica (Cerca / Chiedi all'AI)
`search-config.json`	generato in `templates/infocad/public/`	ponte di config verso il browser (endpoint + chiave search-only). Non versionato.

Flusso dei dati:

docs/  --build.sh-->  _site/**.html  --index.py-->  Typesense (collection infocad_docs)
browser  --search-only key-->  Typesense /multi_search            (Cerca)
browser  --search-only key-->  Typesense /multi_search?conversation=true  --server-side--> OpenAI  (Chiedi all'AI)

Setup iniziale (una volta)

cd docs-site/search
cp .env.example .env
# compila .env:
#   TYPESENSE_API_KEY   -> genera con: openssl rand -hex 32   (chiave admin, resta sul server)
#   OPENAI_API_KEY      -> la tua chiave OpenAI (solo server-side; lascia vuoto per disattivare la RAG)
#   PUBLIC_TYPESENSE_URL-> endpoint che i BROWSER useranno (vedi sotto)

docker compose up -d          # avvia Typesense (healthcheck su :8108/health)

`PUBLIC_TYPESENSE_URL`: locale vs intranet

Dev locale (ognuno sul proprio PC): http://localhost:8108. In docker-compose.yml la porta e' gia' esposta solo su 127.0.0.1.
Deploy intranet condiviso: metti l'URL raggiungibile dai browser del team, es. http://docs-typesense.intranet.descor:8108 (meglio dietro reverse proxy HTTPS). In docker-compose.yml cambia il binding in 0.0.0.0:8108:8108 (o esponi solo il proxy) e tieni --enable-cors.

Costruire e indicizzare

Un solo comando fa build + bootstrap + indicizzazione nell'ordine giusto:

docs-site/scripts/reindex.sh
docs-site/scripts/serve.sh      # -> http://localhost:8080

Oppure a mano:

docs-site/scripts/build.sh          # docs/ -> _site
python3 docs-site/search/bootstrap.py
python3 docs-site/search/index.py

bootstrap.py e' idempotente: riusa la chiave search-only gia' presente e non ricrea cio' che esiste. index.py ricrea la collection infocad_docs a ogni run, quindi non restano documenti orfani di pagine cancellate.

Manutenzione ordinaria

Situazione	Comando
Hai aggiornato le pagine `docs/`	`docs-site/scripts/reindex.sh` (o solo `build.sh` + `index.py`)
Hai cambiato `OPENAI_API_KEY` o il modello	modifica `.env`, poi `python3 bootstrap.py --update-model`
Vuoi rigenerare la chiave search-only del frontend	`python3 bootstrap.py --rotate-key`
Cambio di modello OpenAI	in `.env` `RAG_MODEL_NAME=openai/gpt-4o` (o `openai/gpt-4o-mini`), poi `--update-model`

Diagnostica

La barra usa lunr invece di Typesense -> manca _site/public/search-config.json o ha "enabled": false. Rilancia bootstrap.py (verifica che scriva anche in _site/public/).
"Ricerca non disponibile / Failed to fetch" nel modale -> il browser non raggiunge PUBLIC_TYPESENSE_URL, oppure CORS/porta. Verifica curl $PUBLIC_TYPESENSE_URL/health dal client e il binding in docker-compose.yml.
"Chiedi all'AI" non compare -> OPENAI_API_KEY vuota al momento del bootstrap.py (RAG disattivata). Compila .env e python3 bootstrap.py --update-model.
"Chiedi all'AI" da' errore -> il server Typesense non ha rete in uscita verso OpenAI, o la chiave e' scaduta/senza credito. Controlla i log: docker compose logs typesense.
Ricerca a zero risultati dopo modifiche -> hai indicizzato prima di ricostruire _site. L'ordine e' sempre build -> index.

Runbook completo con schema dei record e API: docs-site/search/README.md.

Table of Contents