KOMPAS-3D GUARD-600M
Семантический поиск по API КОМПАС-3D
Что это
Модель-эмбеддер, которая превращает запрос инженера на живом языке в вектор и
находит нужный элемент API КОМПАС-3D. Спрашиваете «как получить радиус окружности» —
получаете ICircle.Radius. Спрашиваете «плоскость XOY» — получаете o3d_planeXOY.
Универсальные модели поиска на этой задаче работают плохо. API КОМПАС-3D — это
десятки тысяч близких по смыслу методов, свойств и перечислений с русскими
описаниями и английскими именами. IView.Scale и IView.ScaleValue,
IPart7.Name и IPart7.FileName — для общей модели это почти одно и то же,
а для инженера разница принципиальная.
Эта модель обучена именно на такой разметке и различает такие пары.
KOMPAS-3D GUARD-600M — максимальное качество в линейке. Для случаев, где важна точность, а не миллисекунды.
Результаты
Поиск по корпусу из 38 249 документов API КОМПАС-3D на двух наборах по 1 000 запросов каждый:
- Semantic Route — обычные инженерные запросы на русском и английском.
- Hard Disambiguation — запросы про похожие сущности, которые легко спутать.
Метрики этой модели
| Метрика | Semantic Route | Hard Disambiguation |
|---|---|---|
| Recall@1 | 33,7% | 34,6% |
| Recall@3 | 74,1% | 75,3% |
| Recall@5 | 89,1% | 88,8% |
| MRR@10 | 56,2% | 56,8% |
| nDCG@10 | 65,8% | 66,3% |
Recall@5 означает: нужный элемент API попал в первые пять результатов.
Вся линейка
| Модель | Параметры | dim | Semantic RouteRecall@5 | Hard DisambiguationRecall@5 |
|---|---|---|---|---|
| KOMPAS-3D GUARD V1 (предыдущее поколение) | 34M | 384 | 59,2% | 58,1% |
| KOMPAS-3D GUARD-34M | 34,4M | 384 | 70,2% | 67,5% |
| KOMPAS-3D GUARD-150M | 149,0M | 768 | 82,5% | 79,5% |
| KOMPAS-3D GUARD-600M — эта модель | 595,8M | 1024 | 89,1% | 88,8% |
Относительно предыдущего поколения KOMPAS-3D GUARD-600M даёт +29,9 п.п. на Semantic Route и +30,7 п.п. на Hard Disambiguation по Recall@5.
Сырые числа — в benchmarks/metrics.json.
Быстрый старт
pip install sentence-transformers
from sentence_transformers import SentenceTransformer
model = SentenceTransformer("dwnmf/KOMPAS-3D-GUARD-600M")
# Запрос идёт с инструкцией, документ — БЕЗ префикса.
queries = model.encode(
["как получить радиус окружности", "сохранить деталь в файл"],
prompt_name="query",
normalize_embeddings=True,
)
documents = model.encode(
["ICircle.Radius — радиус окружности", "IKompasDocument.Save — сохранить документ"],
normalize_embeddings=True,
)
scores = queries @ documents.T
print(scores)
prompt_name="query" подставляет инструкцию, с которой модель обучалась:
Instruct: Given a user request about the KOMPAS-3D API, retrieve the API method or documentation route that best satisfies it
Query:{текст запроса}
Документы кодируются без префикса. Инструкция зашита в конфиг модели — не заменяйте её стандартной инструкцией Qwen3, качество упадёт.
Важно. Корпус и запросы должны кодироваться одной и той же моделью и в одной точности. Если проиндексировать документы одной моделью или в другой разрядности, а запросы гонять через другую, векторные пространства не совпадут и качество упадёт сильнее, чем от любого выбора модели по отдельности.
Какую модель выбрать
| Задача | Модель |
|---|---|
| Локальный запуск, CPU, десятки тысяч запросов | 34M |
| Универсальный выбор для продакшена | 150M |
| Максимальная точность, есть GPU | 600M |
Характеристики
| Параметры | 595,8 млн |
| Размерность вектора | 1024 |
| Максимальный контекст | 32768 токенов |
| Слоёв | 28 |
| Архитектура | Qwen3 |
| Пулинг | last token |
| Метрика близости | косинусная |
| Базовая модель | Qwen/Qwen3-Embedding-0.6B |
| Вес | 1,19 ГБ (bfloat16) |
| Языки | русский, английский |
Границы применимости
Модель делает одну вещь и делает её хорошо — ищет элементы API КОМПАС-3D. Что важно понимать:
- это эмбеддер, а не генератор: он не пишет код и не отвечает текстом;
- вне домена КОМПАС-3D качество не гарантируется — для общего поиска берите базовые модели deepvk/USER2 или Qwen3-Embedding;
- модель отражает состав API на момент сборки корпуса и не знает о более новых методах;
- поиск возвращает кандидатов, а не гарантию: в продакшене результат стоит проверять компилятором и графом вызовов.
Лицензия
CC BY-NC 4.0 — только некоммерческое использование.
Коммерческое использование весов, индексов и производных артефактов требует отдельного письменного разрешения. Напишите на hello@kompasmcp.ru — коммерческие лицензии выдаются.
Базовая модель Qwen/Qwen3-Embedding-0.6B
распространяется под Apache-2.0; условия апстрима сохраняются для его
компонентов. Ограничение CC BY-NC 4.0 распространяется на КОМПАС-специфичный
файнтюн и упакованные артефакты этого репозитория. Подробнее —
LICENSE.md и NOTICE.md.
Контакты
- Почта — hello@kompasmcp.ru
- Telegram — t.me/lya_ocean
- SDK — github.com/dwnmf/kompas-3d-guard-bin
Три модели. Один SDK.