Konfiguracja, Lokalny Start i Docker

Konfiguracja jest ładowana ze zmiennych środowiskowych w backend/config.py. Sekrety trzymaj lokalnie albo w secret variables CI/CD. Nie kopiuj wartości z jarvis-dev.env do dokumentacji, commitów ani logów.

Zmienne Środowiskowe

Flask

Database

Redis, Sesje i Rate Limiting

OpenAI

Memory Service

Przykład lokalnego extractora:

MEMORY_EXTRACTOR_PROVIDER=local_llm
MEMORY_LLM_BASE_URL=http://local-llm:11434/v1
MEMORY_LLM_API_KEY=local
MEMORY_LLM_MODEL=qwen2.5:3b-instruct
MEMORY_MIN_CONFIDENCE=0.7

Jeśli lokalny LLM zwróci niepoprawny JSON albo nie odpowie, worker używa fallbacku heurystycznego.

Speaches

Backend czyta data[].id jako dostępne modele TTS oraz data[].voices[] jako głosy. UI grupuje głosy po language; po wyborze głosu automatycznie ustawia powiązany model TTS z pola model_id.

Chatterbox TTS

Chatterbox TTS Server może działać jako alternatywny provider server-side TTS. W Compose jest dostępny jako opcjonalny profil chatterbox, więc nie startuje przy zwykłym docker compose up.

Przykład:

SPEECH_TTS_PROVIDER=chatterbox
CHATTERBOX_TTS_ENABLED=true
CHATTERBOX_TTS_BASE_URL=http://chatterbox:4123
CHATTERBOX_TTS_VOICE=alloy

Aktualna integracja używa OpenAI-compatible endpointu /v1/audio/speech z travisvn/chatterbox-tts-api. Ten serwis ma także endpoint /v1/audio/speech/stream, więc prawdziwe streaming audio może być kolejnym krokiem po potwierdzeniu jakości i stabilności providera.

Discord

Azure Boards

reCAPTCHA

Observability

STT raportuje metryki speech.stt.* przez OpenTelemetry, jeśli OTEL_METRICS_ENABLED=true i ustawiono endpoint OTLP. Najważniejsze serie to:

• speech.stt.requests - licznik requestów według source, model, language i status,
• speech.stt.queue_wait_ms - czas oczekiwania na limiter STT,
• speech.stt.elapsed_ms - czas wywołania Speaches,
• speech.stt.audio_bytes i speech.stt.audio_duration_ms - rozmiar i długość audio,
• speech.stt.transcript_chars - długość transkryptu.

source=web oznacza web voice mode, a source=discord oznacza request z Discord bota przez internal API.

Uruchomienie Lokalne

1. Utworzenie środowiska

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -r requirements-dev.txt

Linux/macOS:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -r requirements-dev.txt

2. Minimalne zmienne dla startu bez Compose

PowerShell, przykład SQLite:

$env:FLASK_APP = "app.py"
$env:FLASK_SECRET_KEY = "dev-secret"
$env:SQLALCHEMY_DATABASE_URI = "sqlite:///dev.db"
$env:SQLALCHEMY_TRACK_MODIFICATIONS = "False"
$env:AUTO_CREATE_DB = "true"
$env:OPENAI_API_KEY = "test"
$env:OTEL_ENDPOINT = ""
$env:SESSION_TYPE = "filesystem"
$env:RATELIMIT_STORAGE_URI = "memory://"

3. Start aplikacji

python -m flask run --host=0.0.0.0 --port=8000

Po starcie:

• aplikacja: http://localhost:8000/,
• healthcheck: http://localhost:8000/livenez.

Docker

Dockerfile jest multi-stage:

• builder - instaluje zależności runtime do /env,
• runtime - obraz aplikacyjny,
• tester - opcjonalny stage z zależnościami developerskimi,
• production - finalny domyślny obraz produkcyjny.

Build Produkcyjnego Obrazu

docker build -t voice.assistant.web:local .

Uruchomienie Produkcyjnego Obrazu

docker run --rm -p 8000:8000 \
  -e SQLALCHEMY_DATABASE_URI="sqlite:////tmp/test.db" \
  -e SQLALCHEMY_TRACK_MODIFICATIONS="False" \
  -e FLASK_SECRET_KEY="dev-secret" \
  -e OPENAI_API_KEY="test" \
  -e OTEL_ENDPOINT="" \
  voice.assistant.web:local

Build Stage Testowego

docker build --target tester -t voice.assistant.web:tester .

Stage tester jest przeznaczony wyłącznie do narzędzi developerskich. Finalny obraz produkcyjny nie powinien zawierać pytest, flake8, mypy, black ani pre-commit.

Docker Compose

docker-compose.yml uruchamia:

• db - Postgres z pgvector,
• db-init - jednorazowe utworzenie tabel w świeżej lokalnej bazie,
• redis - sesje, rate limits, TTS cache i kolejka pamięci,
• web - aplikacja Flask/Gunicorn,
• memory-worker - worker pamięci z tego samego obrazu aplikacji,
• local-llm - Ollama,
• local-llm-models - bootstrap modelu qwen2.5:3b-instruct,
• speaches - lokalny serwis speech,
• speaches-models - bootstrap modeli TTS,
• chatterbox - opcjonalny lokalny serwis TTS pod profilem chatterbox,
• mockserver - lokalny mock reCAPTCHA.

Compose domyślnie korzysta z jarvis-dev.env. W CI template ustawia JARVIS_ENV_FILE=.ado/env/compose-integration.env, żeby testy nie wymagały lokalnego pliku ani sekretów.

Start:

docker compose up --build

Po uruchomieniu:

• aplikacja: http://localhost:8000/,
• healthcheck: http://localhost:8000/livenez,
• MockServer: http://localhost:1080/,
• Postgres: localhost:5432,
• Speaches UI/API hostowo: http://localhost:8001/,
• Chatterbox API hostowo po starcie profilu: http://localhost:4123/,
• lokalny LLM hostowo: http://localhost:11434/.

Chatterbox TTS

Chatterbox jest zdefiniowany jako opcjonalny serwis Compose. Lokalny wrapper docker/chatterbox/Dockerfile.cpu klonuje upstreamowe repozytorium travisvn/chatterbox-tts-api podczas builda i instaluje wariant CPU. Pierwszy build może potrwać, bo Docker pobiera repozytorium, zależności i modele.

Start samego serwisu:

docker compose --profile chatterbox up --build chatterbox

Start całego stacka razem z Chatterbox:

docker compose --profile chatterbox up --build

Aby backend używał Chatterbox, ustaw w pliku wskazanym przez JARVIS_ENV_FILE:

SPEECH_TTS_PROVIDER=chatterbox
CHATTERBOX_TTS_ENABLED=true
CHATTERBOX_TTS_BASE_URL=http://chatterbox:4123

Modele, głosy i dane long-text jobs są trzymane w nazwanych wolumenach chatterbox_models, chatterbox_voices i chatterbox_longtext_data. Serwis wystawia też dokumentację API pod http://localhost:4123/docs.

Modele Lokalnego LLM

local-llm-models pobiera model przez API Ollamy. Jeśli trzeba wymusić ponowny bootstrap:

docker compose run --rm local-llm-models

Modele Speaches

Speaches nie pobiera modelu TTS automatycznie tylko dlatego, że aplikacja ma go wpisanego w konfiguracji. Bootstrap modeli:

docker compose run --rm speaches-models

Usługa speaches-models czeka na API Speaches, pobiera modele STT z katalogu backend/data/speaches-stt-models.txt używanego też przez panel web jako AVAILABLE_SPEACHES_STT_MODELS, czyta katalog backend/data/speaches-voices.json, wybiera modele TTS mające głosy w językach z SPEACHES_TTS_MODEL_LANGUAGES i uruchamia uvx speaches-cli model download dla każdego z nich. Modele są zapisywane w wolumenie speaches_cache.

Awaryjnie można nadal wymusić konkretną listę modeli przez SPEACHES_STT_MODELS lub SPEACHES_TTS_MODELS, rozdzieloną przecinkami lub średnikami. SPEACHES_STT_MODELS ma pierwszeństwo przed listą panelu dla STT, a SPEACHES_TTS_MODELS ma pierwszeństwo przed filtrem języków dla TTS.

Migracje

Migracje bazy danych są uruchamiane osobną usługą pod profilem migrations:

docker compose --profile migrations run --rm migrate

Pierwsze wdrożenie na istniejącej produkcyjnej bazie bez tabeli alembic_version powinno użyć jednorazowo:

DB_MIGRATION_BOOTSTRAP=true docker compose --profile migrations run --rm migrate

Po bootstrapie kolejne deploye powinny uruchamiać tylko standardowe flask db upgrade przez usługę migrate, bez DB_MIGRATION_BOOTSTRAP=true.