Skip to content

LOCAL_DEMO.md

Latest commit

 

History

History
208 lines (144 loc) · 7.52 KB

LOCAL_DEMO.md

File metadata and controls

208 lines (144 loc) · 7.52 KB
Raw

Локальный запуск NL→SQL (full-source)

Рекомендуемый способ доставки и демо — полный исходный checkout на локальной машине владельца, со своими ключами провайдера. UI, Streamlit-режим и продуктовый pipeline те же, что в приложении; Hugging Face не нужен для запуска.

Launcher: scripts/run_local_demo.py

  • все 12 SQLite-баз (полный registry);
  • полный Chroma-индекс (schema_chunks + few-shot);
  • штатный Streamlit UI на loopback 127.0.0.1 (порт по умолчанию 8501);
  • генератор по умолчанию: mistral / codestral-latest;
  • ключ только из gitignored .env или из окружения процесса — не из CLI.

HF publish/filter/upload/prune и scripts/deploy_hf.py — опциональный исторический tooling. Он не вызывается локальным launcher'ом и не является активным путём доставки.

Два уровня checkout

Уровень Что в дереве Когда хватает
Clone-first 9 небольших SQLite DB + prebuilt chroma_data/ быстрый smoke UI (streamlit run app/streamlit_app.py)
Full-source local все 12 SQLite DB + Chroma, покрывающий те же 12 id scripts/run_local_demo.py (рекомендуемый full demo)

Чистый git-клон не равен full-source: три крупные BIRD-базы не едут в GitHub из-за лимита размера. На уже подготовленной машине (все 12 + полный индекс) шаги download/reindex повторять не нужно.

Требования

  • Windows PowerShell 5.1 или новее (команды ниже совместимы с 5.1);
  • Python 3.13;
  • uv;
  • собственный MISTRAL_API_KEY (embeddings всегда идут через Mistral).
python --version
uv --version

Быстрый запуск (full-source)

1. Корень репозитория

Выполняйте команды из корня клона (каталог, где лежат app/, scripts/, pyproject.toml). Конкретный путь зависит от вашей машины.

# Пример (подставьте свой путь к клону):
# Set-Location C:\path\to\NL_SQL

2. Зависимости

uv sync --extra dev --extra ui

3. API-ключ владельца

Создайте локальный .env, только если его ещё нет:

if (-not (Test-Path -LiteralPath '.env')) {
    Copy-Item -LiteralPath '.env.example' -Destination '.env'
}
notepad .env

В .env задайте (значение не показывайте в отчётах и скриншотах):

MISTRAL_API_KEY=

Заполните ключ вручную. Не передавайте его параметром командной строки и не вставляйте секрет в однострочные env-присваивания в документации, скриптах, логах или скриншотах. .env в .gitignore; публиковать его нельзя.

4. Preflight (без сети)

uv run python scripts/run_local_demo.py --check

При успехе launcher печатает строку preflight OK: full-source checkout с 12 SQLite DB + Chroma и подтверждение, что MISTRAL_API_KEY настроен (значение ключа не печатается). Пример формы (точная пунктуация может совпадать с текущим launcher'ом):

[local-demo] preflight OK: full source checkout (12 SQLite DBs + Chroma); MISTRAL_API_KEY configured (value not printed).

--check не ходит во внешний API и не тратит квоту.

5. Запуск UI

uv run python scripts/run_local_demo.py

Откройте http://127.0.0.1:8501.

Launcher копирует Chroma во временный каталог (NL_SQL_CHROMA_DATA_DIR), чтобы housekeeping Chroma не пачкал tracked chroma_data/ в исходном дереве.

Первый запуск чистого клона → full-source

Если preflight жалуется на неполный набор DB или индекс:

uv run python scripts/download_data.py chinook
uv run python scripts/download_data.py bird-mini-dev
uv run python scripts/build_index.py --db all
uv run python scripts/run_local_demo.py --check

build_index.py вызывает Mistral embeddings и может расходовать квоту вашего ключа. На полностью подготовленной машине эти шаги не нужны.

Health-check работающего UI

$response = Invoke-WebRequest `
    -UseBasicParsing `
    -Uri 'http://127.0.0.1:8501/_stcore/health' `
    -TimeoutSec 15
$response.StatusCode
$response.Content

Ожидается:

200
ok

Smoke в UI (расходует квоту SQL/embed провайдера — только осознанно):

  1. База chinook, режим Fast.
  2. Вопрос: How many albums are in the store?
  3. Ожидание: ответ 347, SQL SELECT COUNT(*) FROM Album.

Остановка

В терминале launcher'а: Ctrl+C.

Другой порт

uv run python scripts/run_local_demo.py --port 8502

Затем http://127.0.0.1:8502.

SQL-генератор (продуктовое подмножество)

Документированный набор для доставки:

NL_SQL_DEFAULT_PROVIDER Ключ / условие
mistral (default) MISTRAL_API_KEY
github_models GITHUB_TOKEN
groq GROQ_API_KEY
ollama локальный Ollama + NL_SQL_OLLAMA_GEN_MODEL

Пример в .env:

NL_SQL_DEFAULT_PROVIDER=mistral

Research/internal имена провайдеров в коде (CLI-мосты, browser bridges и т.п.) не рекомендуются как путь доставки.

Embeddings всегда требуют MISTRAL_API_KEY (mistral-embed), в том числе когда SQL генерирует Ollama.

Типовые ошибки

MISTRAL_API_KEY is not configured

Проверьте, что .env лежит в корне репозитория и значение ключа непустое. Ключ не должен попадать в argv.

Full-source database set is incomplete

Скачайте данные (раздел «Первый запуск чистого клона»).

Chroma index is missing / incomplete index

uv run python scripts/build_index.py --db all

Порт занят

Откройте уже запущенный http://127.0.0.1:8501 или укажите --port.

Связанные файлы

  • Docstring / --help: scripts/run_local_demo.py
  • Обзор в README: раздел Quick start → full-source local demo
  • Опциональный HF tooling (не runtime-зависимость): DEPLOY.md