Ragen: co dowieźliśmy w drugiej połowie września

Druga połowa września miała jeden motyw: mniej rzeczy, które musisz utrzymywać, żeby Ragen działał. Zniknęła jedna wymagana usługa, druga przestała być wymagana.

Jeśli masz już postawiony stack, przeczytaj sekcję o dwóch instalacjach na jednej maszynie przed aktualizacją. Jest tam jedna rzecz do zrobienia ręcznie.

Ragen sam woła dostawców modeli

LiteLLM proxy było usługą, bez której Ragen nie odpowiadał. Przez pierwszą połowę miesiąca stało się jedną z dwóch dróg, a teraz zniknęło jako tryb wbudowany: Ragen woła dostawców bezpośrednio, a tabela tras mówi, który model idzie do kogo.

Zewnętrzny gateway nadal można podłączyć – i to dowolny, który mówi formatem OpenAI: Portkey, vLLM, Ollama, albo samo LiteLLM. Wpisujesz go jako trasę z provider: openai-compatible i podajesz dwie zmienne, LLM_<NAZWA>_BASE_URL i LLM_<NAZWA>_API_KEY. Różnica jest w tym, że to już wybór osoby, która uruchamia instalację, a nie warunek działania produktu.

Dla self-hostera oznacza to jedną usługę i jeden zestaw poświadczeń mniej. Cena jest taka, że poświadczenia dostawców muszą teraz docierać do procesów web, api i worker, a nie tylko do kontenera proxy. Zmienne LLM_GATEWAY, LITELLM_PROXY_URL i LITELLM_MASTER_KEY wypadły ze środowiska.

Klucz Anthropic działa teraz samodzielnie, bez Bedrocka ani Vertexa po drodze. Doszedł też OpenRouter, a instalator proponuje go razem ze Scaleway.

Przy tej zmianie najwięcej uwagi poszło w rzeczy, które mogłyby wyłączyć się po cichu. Reranker Cohere sięgał po adres proxy jako zapasowy i przy nieosiągalnym rerankerze degraduje się do „bez rerankingu”, więc usunięcie proxy wyłączyłoby go bez słowa. Został przepięty. Trzy modele, których worker używa przy zapasowym parsowaniu PDF-ów i przy napisach SRT, nie miały wpisu w tabeli tras i przestałyby działać – dwa z nich są nazwane stałymi w kodzie, dlatego preflight, który istnieje właśnie po to, ich nie widział. Teraz widzi. Syntezę mowy naprawiliśmy przy okazji: była wskazana na proxy, które nie obsługuje audio, więc zwracała 404 w każdym środowisku i nikt tego nie zgłosił, bo nigdy nie działała.

npm run gateway:preflight --probe wykonuje jedno prawdziwe wywołanie na skonfigurowany model i mówi, czy instalacja faktycznie obsłuży to, co ma w konfiguracji.

Kolejki przechodzą na BullMQ

Temporal był silnikiem zadań w tle: ingest dokumentów, nocne harmonogramy, generowanie dokumentów. Teraz jest adapterem, a domyślnym silnikiem jest BullMQ na Redisie. Temporal wypadł z domyślnej instalacji.

Widać to w dwóch miejscach. Obraz workera jest o 180 MB mniejszy, bo wozi dostarcza jeden silnik zamiast dwóch – 1,01 GB zamiast 1,19 GB. I doszedł dashboard kolejek: worker serwuje bull-board od początku. Ustaw WORKER_ADMIN_URL w panelu administracyjnym i w menu pojawi się „Queue Dashboard”.

Jeśli używasz WORKER_RUNTIME=temporal, potrzebujesz przebudowania obrazu. SDK Temporala jest teraz zależnością build-time, więc opublikowany obraz nie wystartuje na Temporalu – zatrzyma się przy starcie. Zbudowanie obrazu workera z devDependencies z apps/worker przywraca działanie.

Ingest przy okazji odchudził się w środku: treść dokumentu przestała podróżować w payloadzie zadania, który skurczył się do dwóch identyfikatorów.

Dwie instalacje na jednej maszynie

docker-compose.yml miał przypisane na sztywno nazwy kontenerów, wolumenów i sieci – ragen-postgres, ragen-postgres-data, ragen-network – zamiast pozwolić Compose’owi dodać prefiks projektu. Te nazwy są globalne dla demona Dockera, więc druga instalacja zderzała się na każdej nazwie kontenera i, co gorsza i czego nikt nie widział, podłączała się do wolumenów Postgresa i Qdranta pierwszej instalacji. Teraz nazwy należą do Compose’a i dwa checkouty współistnieją bez konfigurowania czegokolwiek.

Jeśli masz już postawiony stack, to jest ta jedna rzecz do zrobienia ręcznie. Twoje dane leżą w wolumenach ragen-postgres-data i ragen-qdrant-data. docker compose up po tej zmianie utworzy nowe, puste, nazwane od katalogu projektu (ragen-app_postgres_data). Nic nie zostaje usunięte – stare wolumeny nadal tam są – ale stack wstanie pusty. Żeby zachować dane, przekopiuj je raz, przy zatrzymanym stacku:

docker run --rm -v ragen-postgres-data:/from -v ragen-app_postgres_data:/to \
  alpine sh -c 'cd /from && cp -a . /to'

Podstaw własną nazwę projektu – docker compose config --format json | jq -r .name ją wypisze – i powtórz dla qdrant. Albo zacznij od zera i wgraj dokumenty ponownie.

RAGEN_STACK_NAME zniknęło; tę robotę wykonuje teraz COMPOSE_PROJECT_NAME, a instalator wpisuje je do .env nowej instalacji. To ma znaczenie, bo Compose nazywa projekt od katalogu, więc dwie instalacje w katalogach o tej samej nazwie nadal dzieliłyby wszystko.

Publikowane porty nie mają żadnego prefiksu i nadal się zderzają. Instalator sprawdza je, zanim wystartuje stack, i mówi, który jest zajęty i co ustawić.

API rozmawia formatem OpenAI

POST /v1/chat/completions wymagało pola assistant_id, którego format OpenAI nie ma – więc n8n, SDK OpenAI i wszystko inne mówiące tym protokołem dostawało 400, zanim żądanie dotarło gdziekolwiek. Wybór asystenta przeniósł się na klucz API: klucz sięga albo do jednego asystenta, albo do całej bazy wiedzy, panel mówi do którego, a assistant_id stało się polem opcjonalnym, które musi się zgadzać z kluczem.

Zakres klucza jest granicą, nie domyślną wartością. Klucz wystawiony dla jednego asystenta odrzuci żądanie wskazujące innego, a nie obsłuży je uprzejmie. Ta sama reguła obowiązuje teraz na /v1/chat, /v1/search, /v1/threads, /v1/assistants i /v1/files – więc klucz przekazany zewnętrznemu integratorowi sięga do jednego asystenta, a nie do reszty organizacji, co wcześniej potrafił.

Doszło GET /v1/models, które odpowiada modelami, jakie ta instalacja faktycznie obsługuje i jakich organizacja ma prawo używać. Klient zgodny z OpenAI wypełnia dzięki temu listę modeli, zamiast pokazywać w tym miejscu błąd. Tylko do czytania i węższe, niż brzmi: to przecięcie katalogu, tabeli tras i listy dopuszczonych per organizacja, więc model, który się na liście pojawi, faktycznie odpowie.

Serwer MCP dostał to samo: assistant_id jest w jego narzędziach opcjonalne, bo wcześniej klucz o zakresie całej bazy wiedzy – czyli domyślny – nie mógł ich w ogóle wywołać.

Napisaliśmy o tym osobno, z konfiguracją node po node: n8n pyta, Ragen odpowiada.

Instalator i pierwsze uruchomienie

create-ragen-app doszedł do 0.6.2 i przestał pytać o rzeczy, których świeża instalacja nie potrzebuje, a zaczął pytać o te, które kosztują.

Maskowanie danych osobowych jest teraz pytaniem, a odpowiedzią domyślną jest „nie”. Presidio to dwa kontenery, a sam analyzer jest najcięższą rzeczą w stacku – 959 MB na bezczynnym stacku, więcej niż parser dokumentów – więc instalacja próbna nie płaci już za funkcję, do której większość ewaluacji nie dochodzi. Powiedz „tak” i kreator wpisze oba adresy Presidio oraz uruchomi stack z profilem Compose, za którym te usługi siedzą. Przy okazji dokumentacja przestała twierdzić, że Presidio startuje domyślnie: zwykłe docker compose up nigdy go nie uruchamiało, co czyni bezczynny stack raczej 900-megabajtowym niż 1,9-gigabajtowym.

Świeża instalacja startuje na BullMQ i wpisuje REDIS_URL, którego ten silnik potrzebuje. Jeśli wybierzesz Temporala, kreator zapyta o adres serwera, zamiast wpisywać localhost:7233 w Twoim imieniu. Blok „co dalej” wymienia też npm run worker:dev – bez workera upload jest przyjmowany i nigdy nie parsowany.

Ragen mówi teraz wprost, na których wersjach Node’a działa, i instalator odrzuca pozostałe w pierwszej sekundzie. jsdom, zależność przechodnia, która przyszła bez żadnego podbicia wersji u nas, wymaga ^22.22.2 || ^24.15.0 || >=26.0.0, a repozytorium ma engine-strict=true, więc npm zatrzymuje się zamiast ostrzegać. engines.node mówiło >=24, więc create-ragen-app przepuszczał Node 24.13, klonował, zapisywał .env.local, startował Dockera i dopiero wtedy trafiał w EBADENGINE. Teraz jest ^24.15.0 || >=26.0.0 – zakres, nie minimum, bo ten zakres pomija całą linię Node 25 i żadne >= tego nie powie. Odmowa nazywa powód, co jest tym, co musi usłyszeć ktoś, kto ma już „Node 24” albo nowszego Node.

Zajęty Docker przestał kończyć instalację błędem.

ragen-cli

npm i -g ragen-cli daje komendę ragen. Dziś stawia tylko instalację – ragen create my-app to npx create-ragen-app@latest z tymi samymi flagami – a komendy, których nie ma (login, doctor, kb, plugin), są wymienione w ragen help pod nagłówkiem „Not built yet”.

Krócej

Ponowne indeksowanie dokumentu nie zostawia już starej wersji w indeksie. Każdy re-embed dokładał nowy zestaw fragmentów, nie usuwając poprzednich, więc wyszukiwanie cytowało tekst, który został zastąpiony, i cytowało go dwa razy (#1209)
Odpowiedź mówiąca, że w dokumentach nie ma nic na dany temat, nie nosi już cytowania. Zasada cytowania rozróżniała tylko zdania, które używają kontekstu, i te, które go nie używają – stwierdzenie braku nie jest ani jednym, ani drugim, więc model cytował i tak. Zmierzone: 5 odmów na 50 z cytowaniem przed poprawką, 0 na 50 po (#1218)
GET /v1/files przestało odpowiadać za inne organizacje. Filtrowało po asystencie klucza API, a żaden klucz nigdy go nie nosił, więc filtr nie obejmował niczego. Nic nie wyciekło, bo żaden klucz nie został jeszcze nigdzie wydany – ale pierwszy wydany by wyciekł (#1236)
Anulowanie ingestu działa natychmiast i działa też po tym, jak zadanie przestało być śledzone. Wcześniej było wiadomością wysyłaną w pamięć działającego workflow: plik zostawał „processing” w interfejsie, anulowanie zapomnianego już zadania rzucało błąd, a restart workera gubił żądanie (#1207)
Instalacja, której klucz szyfrujący nie działa, mówi to przy starcie, zamiast zawodzić po jednej wiadomości. Samo ustawienie zmiennych było traktowane jak posiadanie działającego klucza, więc brak uprawnienia albo klucz z innego projektu dawał ogólne „wystąpił nieoczekiwany błąd” przy każdym pytaniu
Domyślna równoległość workera to teraz zmierzona, nie ostrożna: dziesięć kosztowało bulk upload około dwa razy więcej czasu niż dwadzieścia, 24,9 s na dokument wobec 12,5 s (#1221)
Lokalna instalacja bez TEMPORAL_SERVER_ADDRESS wraca do localhost:7233, zamiast łączyć się z literalnym napisem "undefined" (#1203)

Pełna lista wydań: docs.ragen.ai/changelog

Powiązane wpisy:

Chcesz zobaczyć to na swoich dokumentach? Umów bezpłatne demo – w 30 minut pokażemy Ragena na Twoim scenariuszu.