Konfigurace Cordis

Vestavěný modul používá dva dokumenty a proměnné prostředí. Dokumenty jsou výchozím způsobem vedle backendu; LIBRE_CORDIS_CONFIG a LIBRE_CORDIS_SETTINGS je přemístí.

Dokument	Vlastník	Tvar	Účel
cordis.patch.yml	Cordis Loader	YAML pole nejvyšší úrovně	Řádky pluginů načítající modul
cordis.config.yml	Hostitel Libre WebUI	YAML mapa	Poskytovatel, zdroj údajů a přepínače

Dva dokumenty jsou nutné, protože Cordis Include sám čte kompozici a přijímá jen pole nejvyšší úrovně. Nastavení hostitele proto nemůže být ve stejném souboru.

Zapnutí

Správce zapne modul v Nastavení → Správa uživatelů → Přístup a zásady → Modul Cordis. Změna platí ihned: zapnutí spustí modul při dalším požadavku, vypnutí jej uvolní. Restart není potřeba.

Dva zdroje na úrovni nasazení mohou hodnotu připnout. Oba zablokují přepínač místo tichého přepsání:

Zdroj	Účinek
LIBRE_CORDIS_ENABLED proměnná prostředí	true/false připne funkci pro nasazení
features.enabled v cordis.config.yml	Výslovná hodnota připne volbu; bez klíče rozhoduje správce

Modul potřebuje kompozici. Začněte dodanými příklady:

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

Hostitel čte cordis.patch.yml, sloučí své výchozí hodnoty do řádku mostu a zapíše <DATA_DIR>/cordis-runtime/cordis.composed.yml. Generovaný soubor je nahraditelný a neupravuje se; autoritou je operátorův cordis.patch.yml.

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

Klíče nejvyšší úrovně

Klíč	Typ	Výchozí	Význam
trace	boolean	false	Logovat každou aktivaci Cordis
model	mapa	–	Výběr adaptéru modelu; viz níže
features	mapa	–	Přepínače schopností; viz níže

features

Klíč	Typ	Výchozí	Význam
enabled	boolean	false	Načíst modul; při vypnutí každá cesta vrací 503.
streaming	boolean	true	Přijímat streamované tahy modelu
tools	boolean	true	Povolit nástroje a zobrazit registr
persistence	boolean	true	Zapnout a vyžadovat JSONL persistenci; relace přežijí restart

features.enabled je jediný přepínač potřebný k zapnutí. Vrchní enabled se nečte; všechny přepínače v features poskytují jediné místo ke kontrole aktivních schopností.

model

Klíč	Typ	Výchozí	Význam
provider	řetězec	libre-webui	libre-webui, deepseek, pi-ai nebo none
apiKeyEnv	řetězec	OPENAI_API_KEY	Název proměnné prostředí obsahující klíč
route	řetězec	libre-webui	Cesta poskytovatele uváděná v požadavcích
model	řetězec	''	ID požadovaného modelu. Nastavte pro ruční cestu
baseUrl	řetězec	''	Přepsání endpointu; prázdné použije výchozí adaptér
providers	mapa	{}	Ručně deklarované cesty podle názvu

Odkud pocházejí modely modulu

Modul nemá vlastní nastavení poskytovatelů. Volá ty z Libre WebUI přes cestu libre-webui, registrovanou řádkem libre-webui-llm-adapter. Co je dostupné v chatu, může použít i modul: po stažení modelu v UI jej uvidí s již nastavenými údaji a endpointem.

Použijte model.provider: libre-webui, dodanou výchozí volbu. Přihlašovací údaje a endpointy zůstávají ve stávajícím nastavení aplikace.

model pojmenovává požadovaný model. Prázdná hodnota znamená výchozí model aplikace; bez něj se vezme první chatový model poskytovatelů, přednostně dostupný místní. Embeddingy se vylučují. Interní cesty zachovávají poskytovatele i model: lwui:ollama:<encoded-model> nebo lwui:plugin:<encoded-provider>:<encoded-model>. Shodná jména či výpadek Ollama tak nepřesměrují místní požadavek vzdálenému poskytovateli. Výslovně vybraný nedostupný poskytovatel selže, nepřepne se potají.

Prázdný model je bezpečný pouze na libre-webui. Cesta balíčku poskytovatele vyžaduje model: dsh-llm-pi-ai řeší katalogové dotazy, ale nepoužije první položku jako náhradu. Ruční cesta bez model odmítá tah a hlásí:

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

Nastavte model na ID ze seznamu models. Dodaný příklad spojuje route: ollama s model: llama3.2, odpovídajícím deklarované položce llama3.2.

provider vybírá načtený adaptér:

• libre-webui používá vlastní vrstvu poskytovatelů nasazení; jde o podporovaný výchozí režim.
• none spustí modul bez modelu. Nástroje lze vypsat a relace fungují, ale tah není zodpovězen; hodí se k ověření kompozice.
• deepseek a pi-ai načítají balíček přímo. Nejsou závislostmi tohoto backendu: všechna SDK přidávala 59 tranzitivních balíčků včetně zastaralých pro nevyužívané funkce. Instalujte vybraný balíček a jeho řádek; hostitel případný chybějící balíček pojmenuje.

Cestu poskytovatele popisují:

Pole	Význam
displayName	Čitelný název
api	Přenosový protokol, např. openai-completions
baseURL	Základ endpointu
apiKeyEnv	Proměnná s klíčem
models	Seznam modelů; položka přijímá id, name, contextWindow, maxTokens

Přihlašovací údaje se do dokumentů nikdy nezapisují. apiKeyEnv uvádí název proměnné, kterou adaptér čte pro každý požadavek. Rotace klíče nevyžaduje restart.

cordis.patch.yml

Pole položek Loaderu na nejvyšší úrovni. Dodaný příklad s devíti řádky je doporučený základ.

- 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'

Pole položky

Pole	Povinné	Význam
id	ne	Stálé ID řádku; při vynechání odvozené z name
name	ano	Importovaný modul; musí být řetězcový literál
config	ne	Nastavení pluginu; povoleno !!js
disabled	ne	Přeskočit bez odstranění; povoleno !!js
inject	ne	Další potřebné služby nebo konfigurace interceptu

Loader přímo importuje name, nikdy jej nevyhodnocuje, proto nemůže být !!js. Hodnoty config smí používat !!js: vyhodnotí se později ve vlákně řádku s kontextem Loaderu. process.env a ctx.get(...) fungují, import.meta ne.

Relativní specifikátory se řeší proti adresáři souboru kompozice. Prostá jména přes backendový balíček: @deepseek-ai/dsh-tools najde kopii v backend/node_modules.

Pořadí řádků nezpůsobuje pořadí načtení. Cordis aktivuje řádek s dostupnými deklarovanými službami; seskupení je pouze pro čtenáře.

Povinné řádky

Modul odpovídající v chatu potřebuje všechny následující:

Řádek	Poskytuje	Potřebuje
dsh-llm	llm	smyčka agenta
dsh-session	sessions	smyčka agenta, most
dsh-session-projection	sessionProjections	smyčka agenta
dsh-system-prompt	systemPrompt	nástroje, smyčka agenta
dsh-tools	tools	smyčka agenta, most
dsh-agent	agents	most
dsh-agent-loop	ovladač agenta	odpovědi na tahy
řádek mostu	libreDshEngine	všechny cesty

Aby GET /api/cordis/tools vracelo nástroje, načtěte také plugin, například @deepseek-ai/dsh-fs-sandbox s @deepseek-ai/dsh-tool-fs. Registr bez pluginů je oprávněně prázdný.

Proměnné prostředí

Každou hodnotu lze přepsat proměnnou. Prostředí má přednost před dokumentem, dokument před zabudovanou výchozí hodnotou.

Proměnná	Přepisuje	Výchozí
LIBRE_CORDIS_ENABLED	features.enabled	false
LIBRE_CORDIS_STREAMING	features.streaming	true
LIBRE_CORDIS_TOOLS	features.tools	true
LIBRE_CORDIS_PERSISTENCE	features.persistence	true
LIBRE_CORDIS_TRACE	trace	false
LIBRE_CORDIS_MODEL_PROVIDER	model.provider	libre-webui
LIBRE_CORDIS_MODEL_ROUTE	model.route	libre-webui
LIBRE_CORDIS_MODEL	model.model	''
LIBRE_CORDIS_API_KEY_ENV	model.apiKeyEnv	OPENAI_API_KEY
LIBRE_CORDIS_BASE_URL	model.baseUrl	''
LIBRE_CORDIS_CONFIG	Cesta dokumentu kompozice	<cwd>/cordis.patch.yml
LIBRE_CORDIS_SETTINGS	Cesta dokumentu nastavení	vedle kompozičního dokumentu
LIBRE_CORDIS_WORKSPACE	Výchozí pracovní prostor	<DATA_DIR>/cordis-workspace
LIBRE_CORDIS_SESSION_STORE	Adresář uložených relací	<DATA_DIR>/cordis-sessions

Booleovské proměnné přijímají 1/true/yes/on a 0/false/no/off. Nečitelná hodnota se vrátí k dokumentu místo odhadu.

Dodané výrazy !!js čtou i LIBRE_CORDIS_SESSION_STORE a LIBRE_CORDIS_WORKSPACE; hostitel je proto exportuje před načtením stromu.

Praktické příklady

Místní Ollama, zcela 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 klíč ignoruje, ale klient OpenAI jej vyžaduje. Exportujte OLLAMA_API_KEY=ollama, bez vymýšlení tajného údaje. Nic neopustí stroj.

Brána kompatibilní s 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

Oficiální DeepSeek

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

Nastavte DEEPSEEK_API_KEY v prostředí backendu.

Bez poskytovatele, pouze nástroje

features:
  enabled: true
model:
  provider: none

Modul se spustí, relace vznikají a GET /api/cordis/tools vypíše nastavené pluginy. Zpráva selže, protože ji žádný adaptér nemůže obsloužit.

Poznámky k migraci

Most pouze přidává funkci. Vypnutý, jako ve výchozím stavu, nemění dosavadní chování.

Aktualizace existujícího nasazení. Není co dělat. cordis.patch.example.yml a cordis.config.example.yml se nepoužijí, dokud je nezkopírujete a funkci nepovolíte. Neběží migrace, nevzniká tabulka ani se nemění existující datový adresář.

První zapnutí. Zkopírujte příklady a nastavte features.enabled: true; nic dalšího neinstalujte, balíčky modulu už backend obsahuje. První požadavek vytvoří <DATA_DIR>/cordis-workspace, <DATA_DIR>/cordis-sessions a <DATA_DIR>/cordis-runtime. Nové složky pod datovým adresářem zahrnuje jeho záloha či obnova.

Aktualizace modulu. Vyřešené verze jsou v package-lock.json; backend/package.json deklaruje alpha-kompatibilní rozsahy. Aktualizujte vědomě a po npm install ověřte kontrakty poskytovatelů a relací. Novou peer závislost hlásí npm při instalaci, ne při načítání. Formáty modelů a relací patří DSH; jejich změnu popisuje vydání DSH, ne migrace LWUI.

Vrácení. Nastavte features.enabled: false a restartujte, nebo odeberte most z cordis.patch.yml. libreDshEngine se odebere, posluchač uvolní a agenti ukončí. Soubory relací zůstávají daty; odstranění sessionStorePath uvolní místo. Odinstalování balíčků je volitelné a jiné schopnosti aplikace neovlivní.

Existující Chat a Work. Chat získává volbu DSH jen pro správce, s dočasnými relacemi a stávajícím přepisem. Work získává samostatný modul s izolovaným ovladačem a dosavadním sandboxem/schvalováním. Původní modely fungují stejně.

S libre-webui obsahuje výběr Agentů konkrétní dvojice DSH poskytovatel–model i základní profil. Konkrétní volby drží kvalifikovanou identitu, základ používá výchozí model aktivní kompozice. Názvy a souhrny volají poskytovatele přímo bez nástrojů. Vlastní adaptér poskytuje jen základní položku a vyžaduje zvláštní model úloh Ollama nebo pluginu pro tyto funkce.

DSH respektuje správcův přepínač Ollama. Vypnuté modely se nevypisují ani neověřují a výslovná volba Ollama selže bez změny poskytovatele. I operátorem připnuté nekvalifikované názvy vyžadují katalog Ollama pro bezpečné vyřešení. V čistě pluginovém nasazení používejte lwui:plugin:<plugin>:<model>.

Provozní hranice

• Hostitelský modul a Chat jsou jen pro správce a solo. Stránka je sdílená konzole s místním JSONL, nelze ji načíst v team. Work používá existující SQL repozitáře.
• Model volá autentizovaný uživatel. Interaktivní tahy používají jeho údaje a výchozí model. Důvěryhodná neinteraktivní kompozice smí explicitně nastavit LIBRE_CORDIS_USER na aktivního správce. Není automatická náhrada nejstarším správcem.
• Hostitelské soubory jsou omezené prostorem. Čtení a zápis ověřují kanonický cíl; relace nesmí mít pracovní adresář mimo kořen. DSH omezení změn trvají. Další pluginy operátora jsou důvěryhodný serverový kód.
• Hostitelské nástroje používají zásady DSH. Stránka má režimy čtení/zápisu a jednorázová schválení bez obejití pracovního kořene. Chat bez UI odmítá nezobrazitelné žádosti. Work používá své schvalování a kontejnery bez hostitelských souborových nástrojů.
• Streamy nesou živý text a dostupné uvažování. Trvalé zprávy uchovají hotový přepis; klienti nedostávají text podruhé.
• Restart a mazání pracují s uloženými relacemi. Prázdné i dokončené relace přežijí restart. Smazání JSONL mostu zastaví zapisovač a odstraní soubor; jiná úložiště potřebují příslušný mazací adaptér.
• Staré chybné logy vyžadují výslovnou opravu. Dřívější zprávy chyběly ID. Přísný čtenář je odmítne, neodhodí. Viz Řešení problémů.
• Názvy se odvozují místně. První lidská zpráva dá krátký název; prázdná relace jej nemá.

Připojení modelů z běžící instance DSH

Volitelný dsh-native-provider poskytuje modely a spojení již nastavené v jiné instanci, například místní webové aplikaci na portu 3080. Instalujte jej do jejího profilu. Volá pouze ctx.llm: klíče zůstávají v DSH, nevznikají relace ani agenti, nečtou se nativní přílohy a nevykonávají nativní nástroje.

Oba procesy potřebují stejný Unix hostitel i účet OS. Výslovný Unix socket má fyzický adresář vlastněný tímto účtem s režimem 0700 a socket 0600. Nevzniká TCP listener ani opakované použití či oslabení webové autentizace DSH. Windows a vzdálené hostitele toto spojení nepodporuje.

Účet OS je místní hranice: jiné jeho procesy mohou socket používat. Spojení nedává oddělené nativní údaje ani izolaci aplikací téhož účtu.

Instalace samostatného pluginu

V DSH → Plugins → Add plugin vložte do Package name or address veřejné URL a klikněte na Install:

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

Na výzvu povolte komponentu. Veřejný balíček 0.1.1 pod Apache-2.0 má sestavený runtime i patch. Nepotřebuje místní sestavení, instalační skripty ani npm runtime závislosti. @libre-webui/dsh-native-provider není publikován do npm; používejte GitHub URL.

Bundle volí <DSH home>/lwui-provider/llm.sock, obvykle $HOME/.dsh/lwui-provider/llm.sock; nastavený DSH_HOME má přednost. Soukromý adresář se vytvoří, pokud chybí. Používejte jeden aktivní most na DSH home, nebo pro další profily přepište socket v uživatelském cordis.patch.yml. Úplná cesta musí být do 100 UTF-8 bajtů a bez symlinkových částí. Přepsání popisuje samostatný konfigurační návod.

Volitelný příkaz CLI:

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

Nahraďte web skutečně běžícím profilem. Po CLI instalaci profil restartujte; živé UI může plugin aktivovat ihned. Respektujte upozornění DSH na restart. Zdrojový kód ani kopie klíčů měnit nemusíte.

Příprava bundle z Libre WebUI

LWUI dodává přípravný skript. Ze zdrojového checkoutu sestavte backend a vytvořte nový výstupní adresář:

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

Npm distribuce už mají sestavený backend i skript; spusťte jen poslední dva příkazy z instalace. Poté restartujte zvolený profil. Oba způsoby přípravy odmítají existující adresáře a obsahují metadata, licenci i instalační poznámky.

Připojení Libre WebUI

Nasměrujte cordis.config.yml na stejný absolutní socket. Pro veřejnou výchozí hodnotu nahraďte /absolute/home skutečným domovem:

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

Nebo nastavte LIBRE_DSH_PROVIDER_SOCKET. Prázdná proměnná vypne spojení i přes cestu v dokumentu. Zapněte Modul Cordis v LWUI. Aktivní správci pak volí nativní modely v DeepSeek Harness modulu Work, na stránce modulu a v Agentech Chat, které navíc vyžadují Modely agentů CLI. Work zachová původní model a ID poskytovatele jako providerType: dsh; dřívější LWUI úlohy drží svou identitu a značku modulu.

Katalog se čte živě. Změna poskytovatele či údajů zneplatní generaci spojení a zruší aktivní požadavky. Nedostupný socket, model či poskytovatel žádost zastaví bez přepnutí na Ollama nebo jinam. Názvy a souhrny volají model přímo bez nástrojů. První verze přijímá text, uvažování a zprávy nástrojů; nativní obrazové a souborové odkazy odmítá.

Údaje patří operátorovi DSH, takže spojení je jen pro správce i při širším Work přístupu. Volání mohou opustit hostitele podle DSH nastavení; Work ukáže upozornění. V team musí mít každý obsluhující worker přístup k nastavenému místnímu spojení; jeho nepřítomnost vykonání zakáže. Vypnutí Cordis či odstranění cesty odebere nativní přístup a zachová úlohy. Zanechá-li pád DSH socket, zastavte vlastnící instanci a odeberte jen tento neaktivní socket před restartem; plugin existující položky nepřepisuje.

Aktualizace nebo odstranění pluginu

Nejprve dokončete či zrušte aktivní požadavky. Starý místní bundle 0.0.0/0.1.0 nahraďte v UI přes Uninstall, Add plugin a uvedené GitHub URL. Vlastní socket zachovejte podporovanou uživatelskou výjimkou profilu. Nativní relace a údaje zůstávají.

Instalaci z GitHub lze aktualizovat CLI:

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

Poté restartujte a ověřte verzi. Vypnutý plugin zůstává vypnutý; zkontrolujte jej před testem. Pro připnutí nebo návrat používejte github:libre-webui/dsh-native-provider#<commit>. Vlastní místní bundle sestavte do nové složky a znovu přidejte; aktualizace místní závislosti nestahuje GitHub.

Chcete-li spojení odebrat, nejprve odstraňte nativeProvider.socketPath v LWUI nebo vyprázdněte LIBRE_DSH_PROVIDER_SOCKET, pak spusťte:

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

Restartujte profil. Úlohy LWUI zůstávají, ale nativní volání selžou do obnovení téhož výslovného spojení. Plugin nemaže poskytovatele ani údaje DSH. Staré generované složky mažte až po skončení jejich instalovaného použití.

Využití nativního poskytovatele

Požadavky se ukazují ve Využití poskytovatelů pod DeepSeek Harness · provider s původním modelem. Každý skutečný požadavek se počítá jednou, včetně kol nástrojů, názvů a souhrnů. Přehled obsahuje úspěchy, chyby, zrušení, latenci a hlášené tokeny. Cache vstup se započte jednou; chybějící údaje zůstávají neměřené, neodhadují se. ID dsh-native:<percent-encoded-native-provider-id> používají běžná pravidla tarifů a nákladů. Neznámý tarif zůstává neoceněný.

DSH přes LWUI zachovává záznam poskytovatele. Čtení katalogů a odmítnutí před inferencí nevytváří další volání. Měření začíná instalací této verze, nevymýšlí historii. Ukládá identitu, stav, čas a počítadla, nikdy prompty, odpovědi, údaje, endpointy ani text chyby poskytovatele.

Ověření konfigurace

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" }
  ]
}

503 s code: CORDIS_UNAVAILABLE znamená nenačtenou kompozici. error dává důvod, LIBRE_CORDIS_TRACE=true přidá aktivační log. Příčiny popisuje Řešení problémů.