# Горнорудная база знаний — руководство

**Адрес:** https://mining.sklyarfamily.ru
**Состояние на 28.07.2026:** 50 документов · 3,340 страниц · 15,898 фрагментов в поисковом индексе · 3 готовых досье
**Языки источников:** en — 43, ru — 6, fr — 1

Это не цифровая библиотека, а **слой проверяемой экспертизы**. Ключевое свойство: любой ответ
привязан к книге и странице, и эту страницу можно открыть и увидеть скан. Ничего не выдумывается
«по памяти» — либо есть источник, либо честно сказано, что источника нет.

---

## 1. Как устроен поиск

Запрос проходит три ступени, и это принципиально:

1. **Расширение запроса.** Вопрос разворачивается в 9–15 поисковых формулировок **на русском,
   английском и китайском** — независимо от языка вопроса. Плюс подтягиваются связанные сущности:
   спросив про медь, вы автоматически ищете ещё и медный концентрат, катодную медь, флотацию, ключевые месторождения.
2. **Гибридный отбор.** Параллельно работают семантический поиск (векторы bge-m3) и точный
   полнотекстовый (BM25). Первый находит смысл, второй — конкретные термины, формулы и марки.
3. **Переранжирование.** Кандидаты пересортировываются cross-encoder'ом относительно исходного
   вопроса. Именно этот шаг отсекает «похожее по теме, но не по сути».

### Поиск по минеральным формулам
Работает и по названиям, и по формулам минералов — на любой раскладке:
`CuFeS2` (халькопирит), `Fe3O4`, `Ca5(PO4)3F` (фторапатит).
Формула сначала опознаётся как минерал/вещество, затем ищется по всем его названиям на трёх языках.

---

## 2. Разделы сайта

| Раздел | Что делает |
|---|---|
| **Обзор** | Дашборд: статистика, актив дня, случайные факты, быстрый поиск с автодополнением. Плитки разделов кликабельны и ведут в отфильтрованную библиотеку. |
| **Библиотека** | Все документы с карточками (название, аннотация, темы, ключевые активы). Фильтры по разделу, коллекции и тегам. Поиск внутри библиотеки показывает, **где именно** в каждой книге встретился запрос. |
| **Чат** | Вопрос-ответ по базе. Ответ даётся в двух частях: строго по источникам и отдельно — общие знания модели. Ссылки в квадратных скобках кликабельны и открывают скан страницы. |
| **Досье** | Полное досье на сырьё, актив (месторождение/рудник) или компанию: запасы, лицензии, добыча, переделы, рынок. Экспорт в PDF. Раздел готовых досье пересобирается ежемесячно. |
| **Загрузить** | Приём новых документов (PDF, DjVu, DOCX, XLSX, ZIP, EML, картинки). Сканы распознаются OCR, карточка генерируется автоматически. |
| **Q&A** | Этот документ и подключение внешних ИИ. |

---

## 3. Подключение внешних ИИ

База отвечает по HTTP без авторизации — подключить можно что угодно.

### 3.1. Claude Desktop / Claude Code (MCP)

В `claude_desktop_config.json`:

Инструменты `mine_*` (поиск, досье, verify, оценки запасов) подключаются к Claude Desktop
через MCP-сервер daemon — тем же способом, что и `chem_*` для химической базы. До их
установки универсальный путь — OpenAPI-схема ниже (п. 3.2): она работает из любого агента.

### 3.2. Custom GPT / любой агент с Actions

Скормите схему — больше ничего не нужно:

```
https://mining.sklyarfamily.ru/api/v1/openapi.json
```

Появятся операции `searchLibrary`, `askLibrary`, `lookupFormula`, `getDocument`.

### 3.3. Любой чат — просто дайте ему это в системный промпт

```
У тебя есть доступ к горнорудной базе знаний (50 документов, RU/EN/ZH: технические
отчёты, госдоклады, отраслевые публикации), где каждый факт привязан к документу и странице.

Перед ответом на вопрос по месторождениям, запасам, лицензиям, добыче, обогащению
или переделам — обратись к базе:

  https://mining.sklyarfamily.ru/api/v1/search?q=ЗАПРОС&k=8

Вернётся JSON с дословными фрагментами: title (документ), page (страница), text (цитата),
page_image (скан страницы). Отвечай ТОЛЬКО по этим фрагментам и ставь ссылку
[документ, с.N] после каждого утверждения. Категории запасов/ресурсов цитируй дословно, с датой оценки. Если в базе ответа нет — скажи об этом прямо,
не заменяй его общими знаниями молча.

Формулы минералов можно искать напрямую: https://mining.sklyarfamily.ru/api/v1/formula/CuFeS2
```

### 3.4. Командная строка

```bash
curl "https://mining.sklyarfamily.ru/api/v1/search?q=запасы+фосфоритов+Каратау&k=5"
curl "https://mining.sklyarfamily.ru/api/v1/ask?q=Какие+технологии+обогащения+применяются+для+апатита"
curl "https://mining.sklyarfamily.ru/api/v1/formula/CuFeS2"
```

---

## 4. Справочник API

| Метод | Назначение | Стоимость |
|---|---|---|
| `GET /api/v1/search?q=&k=` | Поиск. Дословные фрагменты со ссылками на страницы. | бесплатно, без модели |
| `GET /api/v1/ask?q=&k=` | Готовый ответ, обоснованный источниками. | вызывает модель, лимит запросов |
| `GET /api/v1/formula/{f}` | Формула минерала → поиск по всем его названиям. | обычно бесплатно (справочник) |
| `GET /api/v1/document/{book_id}` | Карточка документа: аннотация, темы, активы. | бесплатно |
| `GET /api/pageimg/{book_id}/{n}` | Скан страницы (PNG) — доказательство факта. | бесплатно |
| `GET /api/v1/openapi.json` | Схема для Custom GPT Actions. | бесплатно |

**Формат ответа поиска:**
```json
{
  "query": "запасы фосфоритов",
  "results": [
    { "title": "IFA Phosphate Rock Resources and Reserves",
      "book_id": "usgs_mcs_phosphate_2024",
      "page": 143,
      "score": 0.94,
      "text": "World phosphate rock reserves are estimated at…",
      "page_image": "https://mining.sklyarfamily.ru/api/pageimg/usgs_mcs_phosphate_2024/143" }
  ]
}
```

**Лимиты.** Поиск (`/search`, `/formula`, `/document`) не ограничен — он локальный и ничего не стоит.
Генеративные вызовы (`/ask`, чат, досье) ограничены 20 запросами за 10 минут с одного адреса.

---

## 5. Что важно понимать про качество ответов

- **Ответ ровно настолько хорош, насколько полна библиотека.** Если по теме нет книг, база
  честно скажет «нет источников», а не сочинит правдоподобное.
- **Проверяйте по скану.** Ссылка `page_image` — это не украшение, это способ убедиться,
  что цитата настоящая. OCR не идеален, особенно на старых сканах.
- **Рыночные цифры устаревают.** Геология и категории оценок — нет, но оценки сменяются новыми. Досье помечает
  рыночные блоки отдельно; относитесь к ним как к историческому срезу, а не к текущей котировке.
- **Библиотека растёт.** Новые документы попадают в индекс автоматически, в течение часа
  после загрузки.