287 lines
10 KiB
Markdown
287 lines
10 KiB
Markdown
# 1C RAG
|
||
|
||
Цель: подготовить локальный корпус знаний по 1С для поиска и ответов без дообучения модели.
|
||
|
||
## Principles
|
||
|
||
- Сначала RAG и инструменты, потом fine-tuning.
|
||
- Не загружать в репозиторий базы, выгрузки, приватные документы, персональные данные и секреты.
|
||
- Не выдумывать метаданные конкретной базы 1С. Если нужны реквизиты или объекты, использовать tool boundary.
|
||
|
||
## Add Sources
|
||
|
||
Кладем материалы в:
|
||
|
||
```text
|
||
plugins/1c/rag/sources
|
||
```
|
||
|
||
Поддерживаемые форматы:
|
||
|
||
- `.md`
|
||
- `.txt`
|
||
- `.bsl`
|
||
- `.os`
|
||
|
||
## Prepare Corpus
|
||
|
||
```powershell
|
||
python scripts/validate_1c_rag_sources.py --print
|
||
python scripts/prepare_1c_rag_corpus.py
|
||
```
|
||
|
||
Результат:
|
||
|
||
```text
|
||
plugins/1c/datasets/prepared/rag_corpus.jsonl
|
||
plugins/1c/datasets/prepared/rag_manifest.json
|
||
```
|
||
|
||
Этот файл не коммитится.
|
||
|
||
## Test With Example
|
||
|
||
```powershell
|
||
python scripts/prepare_1c_rag_corpus.py --source-dir plugins/1c/rag/examples --output plugins/1c/datasets/prepared/rag_corpus.example.jsonl
|
||
```
|
||
|
||
## Build Search Index
|
||
|
||
```powershell
|
||
python scripts/build_1c_rag_index.py
|
||
```
|
||
|
||
Для синтетического примера:
|
||
|
||
```powershell
|
||
python scripts/build_1c_rag_index.py --corpus plugins/1c/datasets/prepared/rag_corpus.example.jsonl --output plugins/1c/datasets/prepared/rag_index.example.json
|
||
```
|
||
|
||
## Build Vector Index
|
||
|
||
```powershell
|
||
python scripts/build_1c_rag_vector_index.py
|
||
```
|
||
|
||
Результат:
|
||
|
||
```text
|
||
plugins/1c/datasets/prepared/rag_vector_index.sqlite
|
||
```
|
||
|
||
Индекс хранит `corpus_hash`, `embedding_model`, размерность, дату сборки и метаданные чанков.
|
||
Текущий provider `local-hashing-v1` - это локальный deterministic vector baseline, а не нейросемантическая embedding-модель. Он нужен, чтобы отладить формат, freshness и hybrid retrieval без скачивания модели. Нейросемантический provider подключается следующим слоем без смены SQLite-схемы.
|
||
|
||
OpenAI-compatible embedding endpoint:
|
||
|
||
```powershell
|
||
$env:EMBEDDING_API_KEY = "<token-if-needed>"
|
||
python scripts/build_1c_rag_vector_index.py `
|
||
--embedding-provider openai-compatible `
|
||
--embedding-model "<embedding-model-name>" `
|
||
--embedding-base-url "http://docker-gpu.cin.su:8000" `
|
||
--embedding-api-key-env EMBEDDING_API_KEY
|
||
```
|
||
|
||
Для поиска по такому индексу query embedding должен считаться тем же provider/model:
|
||
|
||
```powershell
|
||
python scripts/search_1c_rag_hybrid.py "реквизиты справочника номенклатура" `
|
||
--profile metadata `
|
||
--embedding-base-url "http://docker-gpu.cin.su:8000" `
|
||
--embedding-api-key-env EMBEDDING_API_KEY
|
||
```
|
||
|
||
Ключ не пишется в индекс и читается только из переменной окружения.
|
||
|
||
Полная сборка knowledge base теперь строит corpus, lexical index и vector index:
|
||
|
||
```powershell
|
||
python scripts/build_1c_knowledge_base.py --include-example-bsl
|
||
```
|
||
|
||
Если vector index временно не нужен:
|
||
|
||
```powershell
|
||
python scripts/build_1c_knowledge_base.py --skip-vector-index
|
||
```
|
||
|
||
## Search
|
||
|
||
```powershell
|
||
python scripts/search_1c_rag.py "метаданные справочника" --index plugins/1c/datasets/prepared/rag_index.example.json
|
||
```
|
||
|
||
Поиск использует локальный lexical BM25-подобный индекс с нормализацией 1С-терминов и алиасами вроде `1с/bsl`, `справочник/catalog`, `метаданные/metadata`.
|
||
|
||
Профили RAG лежат в:
|
||
|
||
```text
|
||
plugins/1c/rag/profiles.yaml
|
||
```
|
||
|
||
Основные профили:
|
||
|
||
- `auto`
|
||
- `general`
|
||
- `metadata`
|
||
- `bsl`
|
||
- `query`
|
||
- `safe-change`
|
||
|
||
`auto` выбирает профиль по тексту вопроса. Например, вопросы про реквизиты уходят в `metadata`, вопросы про процедуры и ошибки BSL - в `bsl`, вопросы с `ВЫБРАТЬ` - в `query`.
|
||
|
||
При подготовке корпуса источники получают смысловой `source_type`:
|
||
|
||
- `metadata`
|
||
- `bsl`
|
||
- `query`
|
||
- `safety`
|
||
- `docs`
|
||
|
||
Полезные параметры:
|
||
|
||
```powershell
|
||
python scripts/search_1c_rag.py "реквизиты справочника номенклатура" `
|
||
--index plugins/1c/datasets/prepared/rag_index.example.json `
|
||
--profile metadata `
|
||
--limit 5 `
|
||
--candidate-limit 30 `
|
||
--dedupe-by-document
|
||
```
|
||
|
||
Vector search:
|
||
|
||
```powershell
|
||
python scripts/search_1c_rag_vector.py "реквизиты справочника номенклатура" --profile metadata --limit 5
|
||
```
|
||
|
||
Hybrid search объединяет lexical и vector результаты через reciprocal-rank fusion:
|
||
|
||
```powershell
|
||
python scripts/search_1c_rag_hybrid.py "реквизиты справочника номенклатура" --profile metadata --limit 5
|
||
```
|
||
|
||
Если `vector_freshness.status = stale`, нужно пересобрать vector index после обновления corpus.
|
||
|
||
## Ask With Context
|
||
|
||
Без вызова модели, только сборка prompt:
|
||
|
||
```powershell
|
||
python scripts/ask_1c_rag.py "Какие реквизиты есть у справочника Номенклатура?" --index plugins/1c/datasets/prepared/rag_index.example.json --print-prompt
|
||
```
|
||
|
||
С явным профилем:
|
||
|
||
```powershell
|
||
python scripts/ask_1c_rag.py "Проверь BSL-код процедуры ПередЗаписью" --profile bsl --print-prompt
|
||
```
|
||
|
||
Проверка обязательных правил в prompt:
|
||
|
||
```powershell
|
||
python scripts/check_1c_rag_prompt.py
|
||
```
|
||
|
||
Проверка качества поиска по smoke-набору:
|
||
|
||
```powershell
|
||
python scripts/check_1c_rag_quality.py --print
|
||
```
|
||
|
||
Проверка auto-routing профилей:
|
||
|
||
```powershell
|
||
python scripts/check_1c_rag_profiles.py --print
|
||
```
|
||
|
||
С запущенной моделью:
|
||
|
||
```powershell
|
||
python scripts/ask_1c_rag.py "Какие реквизиты есть у справочника Номенклатура?" --index plugins/1c/datasets/prepared/rag_index.example.json --base-url http://docker-gpu.cin.su:8000 --model qwen3-4b-instruct
|
||
```
|
||
|
||
## Tool Contract
|
||
|
||
Контракт инструментов:
|
||
|
||
```text
|
||
plugins/1c/tools/tool-contract.yaml
|
||
```
|
||
|
||
Главное правило: модель не должна придумывать структуру базы 1С. Если ответ зависит от метаданных, сначала нужен вызов инструмента.
|
||
|
||
## Metadata Snapshot Flow
|
||
|
||
Для проверки RAG на структуре 1С можно сгенерировать source из metadata snapshot:
|
||
|
||
```powershell
|
||
python scripts/validate_1c_metadata_snapshot.py plugins/1c/metadata/examples/metadata.example.json
|
||
python scripts/convert_1c_metadata_to_rag.py --input plugins/1c/metadata/examples/metadata.example.json --output plugins/1c/rag/sources/metadata.example.generated.md
|
||
python scripts/build_1c_knowledge_base.py --include-example-bsl
|
||
python scripts/ask_1c_rag.py "Какие реквизиты есть у справочника Номенклатура?" --print-prompt
|
||
```
|
||
|
||
`build_1c_knowledge_base.py` выполняет валидацию snapshot, конвертацию источников, сборку corpus и индекса за один проход.
|
||
Перед сборкой corpus он также запускает `validate_1c_rag_sources.py`, чтобы заблокировать неподдерживаемые расширения, пустые файлы и вероятные секреты.
|
||
|
||
Manifest содержит source path, source type, file type, content hash и число чанков. Его удобно использовать для аудита и будущего инкрементального обновления индекса.
|
||
|
||
Проверить, не устарел ли manifest относительно `plugins/1c/rag/sources`:
|
||
|
||
```powershell
|
||
python scripts/check_1c_rag_freshness.py --print
|
||
```
|
||
|
||
Статус `stale` означает, что появились новые файлы, изменился hash, был удален источник или изменился `source_type`. После этого нужно пересобрать knowledge base.
|
||
|
||
Проверить, не устарел ли vector index относительно corpus:
|
||
|
||
```powershell
|
||
python scripts/check_1c_rag_vector_freshness.py --print
|
||
```
|
||
|
||
## Semantic Cache Embedding Worker
|
||
|
||
Для live 1C-адаптера semantic cache заполняется отдельно от RAG corpus. Адаптер отдает pending документы с `document_id` и `content_sha1`; worker считает embedding и вызывает `semantic.cache.embedding.upsert`. Если документ изменился, адаптер отвергнет embedding по `content_sha1`.
|
||
|
||
Dry-run:
|
||
|
||
```powershell
|
||
python scripts/embed_1c_semantic_cache.py --base-id upo_test --kind Template --limit 20 --dry-run --json
|
||
```
|
||
|
||
Запись baseline-векторов:
|
||
|
||
```powershell
|
||
python scripts/embed_1c_semantic_cache.py --base-id upo_test --kind Template --limit 20
|
||
```
|
||
|
||
Поиск по semantic cache с автоматически рассчитанным query embedding:
|
||
|
||
```powershell
|
||
python scripts/search_1c_semantic_cache.py "ОбластьШапка" --base-id upo_test --kind Template --limit 5 --validate-candidates
|
||
```
|
||
|
||
Если нужно перед поиском автоматически дозаполнить pending embeddings:
|
||
|
||
```powershell
|
||
python scripts/search_1c_semantic_cache.py "ОбластьШапка" --base-id upo_test --kind Template --embed-pending --validate-candidates
|
||
```
|
||
|
||
С OpenAI-compatible embedding endpoint:
|
||
|
||
```powershell
|
||
$env:EMBEDDING_API_KEY = "<token-if-needed>"
|
||
python scripts/embed_1c_semantic_cache.py `
|
||
--base-id upo_test `
|
||
--kind Template `
|
||
--embedding-provider openai-compatible `
|
||
--embedding-model "<embedding-model-name>" `
|
||
--embedding-base-url "http://docker-gpu.cin.su:8000" `
|
||
--embedding-api-key-env EMBEDDING_API_KEY
|
||
```
|
||
|
||
Semantic cache остается candidate-only: перед программными изменениями использовать `validate_candidates=true` или live read-selector из результата.
|