Passa al contenuto principale

Configurazione Cordis

Il motore Cordis/DSH integrato usa due documenti e alcune variabili d’ambiente. Per impostazione predefinita i documenti sono accanto al backend; LIBRE_CORDIS_CONFIG e LIBRE_CORDIS_SETTINGS ne cambiano la posizione.

DocumentoProprietarioStrutturaScopo
cordis.patch.ymlCordis LoaderArray YAML al livello superioreRighe di plugin che montano il motore
cordis.config.ymlHost Libre WebUIMappa YAMLProvider, fonte delle credenziali, flag delle funzionalità

Servono due documenti perché il componente Cordis Include legge direttamente la composizione e rifiuta file diversi da un array al livello superiore. Le impostazioni dell’host non possono quindi stare nello stesso file.

Abilitazione

Opzione Motore Cordis nelle Impostazioni, accanto all’opzione Agenti.

Un amministratore abilita il motore in Impostazioni → Gestione utenti → Accesso e criteri → Motore Cordis. La modifica è immediata: l’abilitazione avvia il motore alla richiesta successiva; la disabilitazione lo dispone. Non occorre riavviare.

Due fonti di distribuzione possono fissare il valore; entrambe bloccano l’interruttore anziché essere sovrascritte silenziosamente:

FonteEffetto
LIBRE_CORDIS_ENABLED variabile d’ambientetrue/false fissa la funzione per la distribuzione
features.enabled in cordis.config.ymlUn valore esplicito la fissa; omettere la chiave lascia la scelta all’amministratore

Il motore richiede anche una composizione. Parti dagli esempi forniti:

cd backend
cp cordis.patch.example.yml cordis.patch.yml
cp cordis.config.example.yml cordis.config.yml

L’host legge cordis.patch.yml, integra i propri valori predefiniti nella riga del bridge e scrive <DATA_DIR>/cordis-runtime/cordis.composed.yml. Il file generato è eliminabile e non va modificato: il documento autorevole è il cordis.patch.yml dell’operatore.

cordis.config.yml

trace: false

model:
provider: libre-webui
# Empty selects the authenticated caller's configured default/fallback route.
model: ''

features:
# Omit enabled to let the administrator use the Settings toggle.
streaming: true
tools: true
persistence: true

# Optional absolute paths; defaults live under Libre WebUI's data directory.
# workspacePath: /absolute/path/to/workspace
# sessionStorePath: /absolute/path/to/sessions

Chiavi di primo livello

ChiaveTipoPredefinitoSignificato
tracebooleanofalseRegistrare ogni transizione di attivazione Cordis
modelmappaScelta dell’adattatore del modello; vedi sotto
featuresmappaInterruttori delle funzionalità; vedi sotto

features

ChiaveTipoPredefinitoSignificato
enabledbooleanofalseMontare il motore; quando falso ogni route restituisce 503.
streamingbooleanotrueAccettare turni con output del modello in streaming
toolsbooleanotrueConsentire strumenti del motore ed esporne il registro
persistencebooleanotrueAbilitare e richiedere il servizio di persistenza JSONL; le sessioni sopravvivono al riavvio

features.enabled è l’unico interruttore da impostare per accendere il bridge. Una chiave enabled al primo livello non viene letta: tutti gli interruttori sono in features, così esiste un unico punto da controllare.

model

ChiaveTipoPredefinitoSignificato
providerstringalibre-webuilibre-webui, deepseek, pi-ai o none
apiKeyEnvstringaOPENAI_API_KEYNome della variabile d’ambiente contenente la chiave
routestringalibre-webuiRoute provider nominata dal motore nelle richieste
modelstringa''ID del modello richiesto. Impostalo per una route dichiarata manualmente
baseUrlstringa''Endpoint alternativo; vuoto usa il valore dell’adattatore
providersmappa{}Route provider dichiarate manualmente, indicizzate per nome

Da dove provengono i modelli del motore

Il motore non possiede una configurazione provider autonoma. Chiama quelli già presenti in Libre WebUI tramite la route libre-webui, registrata dalla riga libre-webui-llm-adapter. Può usare ciò con cui puoi chattare nell’interfaccia: un modello scaricato lì compare anche al motore, con endpoint e credenziali già configurati.

Imposta model.provider: libre-webui, il valore fornito predefinito. Credenziali ed endpoint restano nelle impostazioni esistenti di Libre WebUI.

model indica il modello richiesto. Vuoto significa “usa il modello predefinito dell’app”; se manca un predefinito, il motore sceglie il primo modello chat segnalato dai provider, preferendo quelli locali disponibili. Gli embedding sono esclusi. Le route interne mantengono provider e modello: lwui:ollama:<encoded-model> o lwui:plugin:<encoded-provider>:<encoded-model>. Questo impedisce che nomi uguali o un’interruzione di Ollama dirottino richieste locali a provider remoti. Un provider selezionato esplicitamente ma indisponibile produce un errore, mai un ripiego silenzioso.

Un model vuoto è sicuro solo sulla route libre-webui. Una route servita da un pacchetto provider richiede un modello esplicito: dsh-llm-pi-ai risolve il catalogo per le interrogazioni, ma non sceglie la prima voce come ripiego. Una route manuale senza model non accetta turni e fallisce con:

provider "<route>" resolves no models; the installed catalog does not describe
this route, so its models must be listed in configuration

Imposta model a un ID nell’elenco models della route. L’esempio fornito associa route: ollama a model: llama3.2, corrispondente alla voce llama3.2 dichiarata.

provider seleziona il pacchetto adattatore montato:

  • libre-webui usa il livello provider della distribuzione. È la modalità supportata e predefinita.
  • none avvia senza accesso al modello. Gli strumenti si elencano e le sessioni funzionano, ma i turni non ricevono risposta: utile per verificare una composizione.
  • deepseek e pi-ai montano direttamente un pacchetto provider. Questi pacchetti non sono dipendenze del backend: includere tutti gli SDK introduceva 59 pacchetti transitivi, anche deprecati, per capacità mai usate dal motore. Installa il pacchetto scelto e montane la riga; se manca, l’host ne indica il nome.

Una route provider è descritta da:

CampoSignificato
displayNameNome leggibile
apiProtocollo di trasporto, ad esempio openai-completions
baseURLBase dell’endpoint
apiKeyEnvVariabile d’ambiente contenente la chiave
modelsElenco modelli; ogni voce accetta id, name, contextWindow, maxTokens

Le credenziali non vengono mai scritte nei documenti. apiKeyEnv nomina una variabile d’ambiente, risolta dall’adattatore per ogni richiesta; ruotare la chiave non richiede riavvio.

cordis.patch.yml

Un array di voci Loader Cordis al livello superiore. L’esempio fornito monta nove righe ed è il punto di partenza consigliato.

- id: llm
name: '@deepseek-ai/dsh-llm'

- id: session
name: '@deepseek-ai/dsh-session'

- id: session-projection
name: '@deepseek-ai/dsh-session-projection'

- id: session-persistence
name: '@deepseek-ai/dsh-session-persistence-jsonl'
config:
# The host supplies the resolved sessionStorePath.

- id: system-prompt
name: '@deepseek-ai/dsh-system-prompt'
config:
personaPrefix: ''

- id: tools
name: '@deepseek-ai/dsh-tools'

- id: agent
name: '@deepseek-ai/dsh-agent'

- id: agent-loop
name: '@deepseek-ai/dsh-agent-loop'
config:
agents: []

- id: libre-webui-bridge
name: './dist/cordis/dsh/engine-plugin.js'

Campi delle voci

CampoObbligatorioSignificato
idnoID stabile per identificare la riga; derivato da name se omesso
nameSpecificatore importato dal Loader; deve essere una stringa letterale
confignoConfigurazione del plugin; consente espressioni !!js
disablednoSaltare la riga senza eliminarla; consente !!js
injectnoUlteriori servizi necessari o configurazione di intercettazione della riga

Il Loader importa direttamente name senza valutarlo: non può essere un’espressione !!js. I valori di config possono usare !!js; vengono valutati successivamente nella fibra proprietaria con il contesto Loader disponibile. process.env e ctx.get(...) funzionano, import.meta no.

Gli specificatori relativi si risolvono rispetto alla directory del file di composizione. Quelli di pacchetto tramite il backend, quindi @deepseek-ai/dsh-tools trova la copia in backend/node_modules.

L’ordine delle righe non determina il caricamento. Cordis le attiva quando i servizi dichiarati esistono; il raggruppamento dell’esempio serve solo alla lettura.

Righe necessarie

Per rispondere in chat il motore richiede tutte queste righe:

RigaFornisceRichiesto da
dsh-llmllmciclo agente
dsh-sessionsessionsciclo agente, bridge
dsh-session-projectionsessionProjectionsciclo agente
dsh-system-promptsystemPromptstrumenti, ciclo agente
dsh-toolstoolsciclo agente, bridge
dsh-agentagentsbridge
dsh-agent-loopdriver dell’agenterisponde ai turni
riga del bridgelibreDshEngineogni route

Per ottenere strumenti da GET /api/cordis/tools occorre montare anche un plugin strumenti, per esempio @deepseek-ai/dsh-fs-sandbox insieme a @deepseek-ai/dsh-tool-fs. Un registro senza plugin è legittimamente vuoto.

Variabili d’ambiente

Ogni impostazione ha una sostituzione d’ambiente. La variabile prevale sul documento, che prevale sul valore integrato predefinito.

VariabileSovrascrivePredefinito
LIBRE_CORDIS_ENABLEDfeatures.enabledfalse
LIBRE_CORDIS_STREAMINGfeatures.streamingtrue
LIBRE_CORDIS_TOOLSfeatures.toolstrue
LIBRE_CORDIS_PERSISTENCEfeatures.persistencetrue
LIBRE_CORDIS_TRACEtracefalse
LIBRE_CORDIS_MODEL_PROVIDERmodel.providerlibre-webui
LIBRE_CORDIS_MODEL_ROUTEmodel.routelibre-webui
LIBRE_CORDIS_MODELmodel.model''
LIBRE_CORDIS_API_KEY_ENVmodel.apiKeyEnvOPENAI_API_KEY
LIBRE_CORDIS_BASE_URLmodel.baseUrl''
LIBRE_CORDIS_CONFIGPercorso del documento di composizione<cwd>/cordis.patch.yml
LIBRE_CORDIS_SETTINGSPercorso del documento di impostazioniaccanto al documento di composizione
LIBRE_CORDIS_WORKSPACEArea di lavoro predefinita del motore<DATA_DIR>/cordis-workspace
LIBRE_CORDIS_SESSION_STOREDirectory delle sessioni persistenti<DATA_DIR>/cordis-sessions

I booleani accettano 1/true/yes/on e 0/false/no/off. Un valore non interpretabile torna al documento anziché tentare una deduzione.

Le espressioni !!js della composizione fornita leggono anche LIBRE_CORDIS_SESSION_STORE e LIBRE_CORDIS_WORKSPACE; per questo l’host li esporta prima di montare l’albero.

Esempi completi

Ollama locale, interamente offline

features:
enabled: true
model:
provider: pi-ai
route: ollama
model: llama3.2
apiKeyEnv: OLLAMA_API_KEY
providers:
ollama:
api: openai-completions
baseURL: http://127.0.0.1:11434/v1
apiKeyEnv: OLLAMA_API_KEY
models:
- id: llama3.2
contextWindow: 131072
maxTokens: 4096

Ollama ignora la chiave, ma il client OpenAI ne richiede una. Esporta OLLAMA_API_KEY=ollama senza inventare un segreto. Nulla lascia la macchina.

Gateway compatibile con OpenAI

features:
enabled: true
model:
provider: pi-ai
route: gateway
model: acme-large
apiKeyEnv: ACME_GATEWAY_API_KEY
providers:
gateway:
displayName: Acme Gateway
api: openai-completions
baseURL: https://gateway.acme.example/v1
apiKeyEnv: ACME_GATEWAY_API_KEY
models:
- id: acme-large
contextWindow: 65536
maxTokens: 4096

DeepSeek ufficiale

features:
enabled: true
model:
provider: deepseek
route: deepseek
apiKeyEnv: DEEPSEEK_API_KEY

Imposta DEEPSEEK_API_KEY nell’ambiente del backend.

Nessun provider, solo strumenti

features:
enabled: true
model:
provider: none

Il motore si avvia, si possono creare sessioni e GET /api/cordis/tools elenca i plugin configurati. Inviare un messaggio fallisce perché nessun adattatore può servirlo.

Note sulla migrazione

Il bridge è aggiuntivo. Quando è spento, come per impostazione predefinita, non cambia il comportamento esistente.

Aggiornare una distribuzione esistente. Non serve alcun intervento. Gli esempi cordis.patch.example.yml e cordis.config.example.yml non vengono letti finché non li copi e abiliti la funzione. Non parte alcuna migrazione, non vengono create tabelle e non vengono toccate directory dati esistenti.

Prima abilitazione. Copia entrambi i documenti e imposta features.enabled: true. Non serve altro: i pacchetti del motore sono già dipendenze backend. Alla prima richiesta vengono create <DATA_DIR>/cordis-workspace, <DATA_DIR>/cordis-sessions e <DATA_DIR>/cordis-runtime, nuove directory dentro quella dati esistente; un backup o ripristino che copre quest’ultima include anche loro.

Aggiornare il motore. package-lock.json registra le versioni risolte; backend/package.json dichiara intervalli compatibili con le versioni alpha. Aggiorna deliberatamente e verifica i contratti di provider e sessioni dopo npm install. Nuove dipendenze peer vengono segnalate da npm all’installazione, non al montaggio. DSH controlla i formati di modelli e sessioni: un cambio di formato appartiene alle note DSH, non a una migrazione Libre WebUI.

Ripristino. Imposta features.enabled: false e riavvia, oppure rimuovi la riga bridge da cordis.patch.yml. Il servizio libreDshEngine viene ritirato, il listener liberato e gli agenti disposti. Le sessioni restano su disco come dati; elimina sessionStorePath per recuperare spazio. Disinstallare i pacchetti è facoltativo e non influisce sulle altre funzioni Libre WebUI.

Chat e Work esistenti. Chat acquisisce la scelta DeepSeek Harness riservata agli amministratori, con sessioni transitorie e trascrizione Chat esistente. Work ottiene una scelta motore distinta tramite driver DSH isolato e flusso sandbox/approvazioni Work esistente. Le selezioni di modelli precedenti mantengono il comportamento normale.

Con libre-webui, il selettore Agenti di Chat include scelte esplicite provider-modello DSH oltre al profilo base. Le scelte esplicite conservano l’identità qualificata; il profilo base usa il modello della composizione attiva. Titoli e riepiloghi del ragionamento chiamano direttamente il provider senza strumenti agente. Una route adattatore personalizzata mantiene solo la voce base e richiede un modello per le attività Ollama o plugin separato per queste funzioni.

DSH rispetta l’interruttore Ollama dell’amministratore. Quando Ollama è disabilitato, i modelli non vengono elencati né interrogati; una scelta Ollama esplicita fallisce senza cambiare provider. Anche nomi non qualificati fissati dall’operatore richiedono il catalogo Ollama per una risoluzione sicura: nelle distribuzioni solo plugin usa lwui:plugin:<plugin>:<model>.

Limiti operativi

  • Motore host e Chat sono solo per amministratori e modalità solo. La pagina è una console condivisa con archivio JSONL locale, non montabile in modalità team. Work isolato usa invece i repository SQL esistenti.
  • Le chiamate al modello usano l’utente autenticato. I turni interattivi usano credenziali e preferenza del modello di quell’amministratore. Una composizione non interattiva fidata può impostare esplicitamente LIBRE_CORDIS_USER sull’ID di un amministratore attivo. Non esiste ripiego implicito sull’amministratore più vecchio.
  • Il filesystem host è confinato all’area configurata. Letture e scritture verificano il percorso canonico; una sessione non può usare una directory esterna alla radice. Restano i vincoli DSH sulle modifiche. Plugin aggiuntivi dell’operatore sono codice server fidato.
  • Gli strumenti host usano le politiche DSH. La pagina Motore offre controlli per sessione sola lettura/scrittura e schede di approvazione nativa singola, senza aggirare la radice configurata. Chat senza interfaccia rifiuta le richieste che non può mostrare. Il driver Work usa invece approvazioni Work e container, senza strumenti filesystem host.
  • Gli stream contengono testo vivo e ragionamento esposto. I messaggi persistenti conservano la trascrizione finale; i client non ricevono una seconda copia del testo.
  • Riavvio ed eliminazione usano sessioni salvate. Sessioni vuote e completate sopravvivono ai riavvii. Eliminare una sessione JSONL del bridge arresta il writer e rimuove il file; altri backend devono fornire un adattatore di eliminazione adatto.
  • I vecchi log malformati richiedono riparazione esplicita. Le prime versioni scrivevano messaggi senza ID. Il lettore rigoroso li rifiuta anziché scartarli. Segui la procedura in Risoluzione dei problemi.
  • I titoli sono derivati localmente. Il primo messaggio umano diventa un titolo breve; le sessioni vuote non hanno un titolo derivato.

Collegare modelli da un’istanza DSH in esecuzione

Il plugin opzionale dsh-native-provider espone modelli e connessioni provider già configurati in un’altra istanza DSH, per esempio l’app web locale sulla porta 3080. Installalo nel profilo esistente. Chiama soltanto ctx.llm: le chiavi restano in DSH e il collegamento non crea sessioni, non esegue agenti o strumenti nativi e non legge allegati nativi.

Entrambi i processi devono usare lo stesso host Unix e account del sistema operativo. Il trasporto usa un socket Unix esplicitamente configurato: directory fisica di proprietà di quell’account con modo 0700, socket con modo 0600. Non aggiunge listener TCP e non riusa né indebolisce l’autenticazione browser DSH. Windows e host DSH remoti non sono supportati.

L’account del sistema operativo è il confine locale: altri processi di quell’account possono usare il socket. Il collegamento non fornisce credenziali native separate né isolamento tra applicazioni dello stesso account.

Installare il plugin autonomo

In DSH → Plugins → Add plugin, incolla questo URL pubblico in Package name or address e premi Install:

https://github.com/libre-webui/dsh-native-provider

Abilita il componente quando DSH lo chiede. Il pacchetto pubblico versione 0.1.1, con licenza Apache-2.0, include runtime compilato e patch del bundle. Non richiede compilazione locale, script di installazione o dipendenze runtime npm. Il nome @libre-webui/dsh-native-provider non è pubblicato su npm: usa l’URL GitHub nel dialogo.

Il bundle sceglie <DSH home>/lwui-provider/llm.sock, normalmente $HOME/.dsh/lwui-provider/llm.sock. DSH_HOME ha precedenza se impostato. La directory privata viene creata se manca. Usa un solo bridge attivo per home DSH oppure cambia il percorso nel cordis.patch.yml utente del profilo per profili aggiuntivi. Il percorso completo deve rientrare in 100 byte UTF-8 e non contenere componenti simbolici. La guida del pacchetto autonomo spiega le sostituzioni.

Equivalente CLI facoltativo:

dsh plugin --profile web add https://github.com/libre-webui/dsh-native-provider

Sostituisci web con il profilo effettivamente in esecuzione, se diverso. Riavvialo dopo l’installazione CLI; quella tramite interfaccia attiva può abilitare subito il plugin. Segui eventuali avvisi di riavvio DSH. Non occorre cambiare i sorgenti DSH né copiare chiavi.

Preparare un bundle da Libre WebUI

Libre WebUI include anche uno script di preparazione. Da un checkout sorgente, compila il backend e crea una directory di output nuova:

npm run build:backend
node scripts/prepare-dsh-provider.mjs /absolute/dsh-provider-bundle /absolute/private-directory/provider.sock
dsh plugin --profile web add /absolute/dsh-provider-bundle

Le distribuzioni npm contengono già backend compilato e script: esegui soltanto gli ultimi due comandi dalla directory installata. Poi riavvia il profilo DSH scelto. Entrambi i percorsi di preparazione rifiutano directory esistenti e includono metadati, licenza e note di installazione.

Collegare Libre WebUI

Punta cordis.config.yml allo stesso percorso socket assoluto. Per il predefinito pubblico, sostituisci /absolute/home con la tua home reale:

nativeProvider:
socketPath: /absolute/home/.dsh/lwui-provider/llm.sock

In alternativa, imposta LIBRE_DSH_PROVIDER_SOCKET a quel percorso. Una variabile vuota disabilita il collegamento anche se il file dichiara un percorso. Abilita Motore Cordis in LWUI: gli amministratori attivi possono scegliere modelli nativi nel motore DeepSeek Harness di Work, nella pagina Motore e nel gruppo Agenti di Chat, che richiede anche Modelli di agenti CLI. Work conserva modello grezzo e ID provider con providerType: dsh; le attività DSH basate su LWUI mantengono provider e indicatore motore originali.

Il catalogo nativo viene letto in tempo reale. Cambi di configurazione o credenziali invalidano la generazione del collegamento e annullano le richieste attive. Socket, modello o provider indisponibili fermano la richiesta: nessun ripiego su Ollama o altri provider. Titoli e riepiloghi usano direttamente l’LLM scelto, senza strumenti. Questo collegamento iniziale accetta testo, ragionamento e messaggi strumenti; riferimenti a immagini o file nativi sono rifiutati.

Le credenziali appartengono all’operatore DSH: il collegamento è solo per amministratori anche se Work è aperto ad altri utenti. I modelli possono contattare servizi esterni secondo il provider DSH; Work mostra l’avviso remoto. In team ogni worker che gestisce queste attività deve raggiungere il collegamento locale configurato, altrimenti l’esecuzione viene rifiutata. Disabilitare Cordis o rimuovere il socket ritira l’accesso nativo conservando le attività. Se un crash DSH lascia un socket, arresta l’istanza proprietaria e rimuovi solo il socket obsoleto prima di riavviare: il plugin non sostituisce voci filesystem esistenti.

Aggiornare o rimuovere il plugin

Completa o annulla le richieste native prima della modifica. Per sostituire il vecchio bundle locale 0.0.0/0.1.0 nell’interfaccia DSH, scegli Uninstall, torna a Add plugin e installa l’URL GitHub sopra. Conserva percorsi personalizzati tramite la sostituzione supportata del profilo utente. Sessioni e credenziali native restano intatte.

Un’installazione già proveniente da GitHub può essere aggiornata da CLI:

dsh plugin --profile web update @libre-webui/dsh-native-provider

Riavvia dopo l’aggiornamento CLI e verifica la versione. Un plugin disabilitato resta tale: controlla lo stato prima di provare la connessione. Per fissare una versione o tornare indietro usa github:libre-webui/dsh-native-provider#<commit>. Per bundle locali personalizzati, crea una nuova directory e aggiungila nuovamente: aggiornare una dipendenza locale non scarica GitHub.

Per rimuovere il collegamento, elimina prima nativeProvider.socketPath da LWUI oppure svuota LIBRE_DSH_PROVIDER_SOCKET, poi esegui:

dsh plugin --profile web remove @libre-webui/dsh-native-provider

Riavvia il profilo DSH. Le attività LWUI restano, ma le richieste native falliscono finché non viene ripristinato lo stesso collegamento esplicito. La rimozione del plugin non elimina provider o credenziali DSH. Cancella le vecchie directory bundle generate solo quando non sono più installate.

Utilizzo dei provider nativi

Le richieste native compaiono in Utilizzo provider sotto DeepSeek Harness · provider, con il modello grezzo selezionato. Ogni richiesta effettiva viene contata una volta, inclusi passaggi strumenti, titoli e riepiloghi. La pagina mostra successi, errori, annullamenti, latenza e token dichiarati da DSH. L’input in cache conta una sola volta nel totale; l’utilizzo mancante resta non misurato, senza stime. Gli ID dsh-native:<percent-encoded-native-provider-id> usano le regole esistenti per tariffe e costi. Senza tariffa il costo resta non determinato.

Le richieste DSH tramite provider LWUI conservano i record esistenti di quei provider. Letture del catalogo e richieste rifiutate prima dell’inferenza non creano chiamate aggiuntive. Il conteggio parte dall’installazione di questa versione; non inventa cronologia. I dati contengono identità, stato, tempo e contatori, senza prompt, risposte, credenziali, endpoint o testo degli errori provider.

Verificare una configurazione

curl -s http://127.0.0.1:3001/api/cordis/health | jq
{
"success": true,
"enabled": true,
"ready": true,
"services": [
{ "name": "llm", "state": "ready" },
{ "name": "systemPrompt", "state": "ready" },
{ "name": "sessions", "state": "ready" },
{ "name": "tools", "state": "ready" },
{ "name": "agents", "state": "ready" }
]
}

Un 503 con code: CORDIS_UNAVAILABLE indica che la composizione non si è montata. error spiega il motivo; LIBRE_CORDIS_TRACE=true aggiunge il registro Cordis. Le cause comuni sono in Risoluzione dei problemi.