# Ollama Embeddings API: индексация и проверка локального поиска

Источник: https://modelium.tech/zhurnal/ollama-embeddings-api/

Ollama создаёт текстовые векторы через локальный POST /api/embed: передайте embedding-модель и строку либо массив строк. Индексируйте фрагменты и запрос одной моделью, затем сравните нормализованные векторы и вручную проверьте найденный фрагмент. Ответ API не доказывает качества поиска или отсутствия сетевых запросов других компонентов; Modelium не запускал этот стек.

**Документация проверена 4 октября 2026 года** на Git-ревизии Ollama `42e911bc3d05`. Это инструкция по первоисточникам, не отчёт о собственном запуске: Modelium не скачивал веса, не получал векторы и не измерял качество поиска [s1](#src-s1)[s2](#src-s2).

## Что именно возвращает Ollama Embeddings API?

Embedding — числовое представление фрагмента текста. Его используют, чтобы искать похожие фрагменты, а затем отдельно передавать найденный текст в языковую модель для ответа. Локальный `POST http://localhost:11434/api/embed` принимает `model` и `input`, где входом служит строка или массив строк; ответ содержит `embeddings` — массив векторов. Это **не** готовая векторная база и не ответ на вопрос по документу [s1](#src-s1)[s2](#src-s2)[s3](#src-s3).

Официальная документация указывает, что `/api/embed` выдаёт L2-нормализованные векторы и советует использовать одну embedding-модель при индексации документов и запросе. Если модель или её вариант изменится, нельзя оставлять старый индекс и считать оценки сопоставимыми: перестройте его и запишите тег/локальный digest в журнал пилота [s1](#src-s1)[s2](#src-s2).

Проверяемый маршрут: **три обезличенных фрагмента документа → **`**embeddinggemma:300m**`** → железо вашего устройства без обещания универсального минимума → локальный Ollama → **`**/api/embed**`** → ранжирование двух фрагментов по запросу → ручная сверка с оригиналом**. В этом примере нет отдельного векторного сервера, чтобы сначала проверить контракт API и смысловую выдачу; для рабочего корпуса понадобится постоянное хранение фрагментов, векторов и метаданных. Указанный тег присутствует в официальной библиотеке, но его качество на ваших русских документах здесь не заявлено [s1](#src-s1)[s6](#src-s6).

## Что установить и как выбрать тег без выдуманных требований к памяти?

Установите Ollama по инструкции для вашей ОС и убедитесь, что локальный API отвечает. В учебном варианте используйте конкретный тег `embeddinggemma:300m`: команда `ollama pull embeddinggemma:300m` скачивает модель; `ollama ls` и `GET /api/tags` позволяют сверить её фактическое имя, а ответ `/api/tags` содержит локальный digest. До загрузки модели нужна сеть; локальная работа после загрузки — отдельная проверка. Инструкция не выводит минимальную RAM/VRAM из размера весов или суффикса `300m` [s4](#src-s4)[s2](#src-s2)[s6](#src-s6)[s5](#src-s5).

Если у вас уже есть `qwen3-embedding`, можно выбрать его **вместо** EmbeddingGemma, но индекс и запрос должны строиться одной и той же выбранной моделью. Размеры и назначение конкретных вариантов смотрите в официальной библиотеке и в [разборе Qwen3 Embedding](/zhurnal/qwen3-embedding/); это альтернатива для собственных тестов, не объявление победителя [s1](#src-s1)[s7](#src-s7).

Откройте [проверку Ollama API](/zhurnal/ollama-healthcheck/), если локальный сервис не отвечает. Ollama по умолчанию привязана к `127.0.0.1:11434`; **не** переносите демонстрационный локальный endpoint на `0.0.0.0` без отдельного контроля доступа. Для собственного хранения индекса заранее исключите реальные договоры, персональные данные и секреты из учебного набора [s5](#src-s5)[s3](#src-s3).

## Как получить векторы и убедиться, что вход не обрезан?

Для пилота придумайте два коротких фрагмента: `Фрагмент 1: договор содержит срок поставки`, `Фрагмент 2: инструкция описывает обновление сервера`. Третий текст — запрос `Где указан срок поставки?`. Сначала отправьте все три в **одном порядке** через JSON-массив: `curl -sS http://localhost:11434/api/embed -H 'Content-Type: application/json' -d '{"model":"embeddinggemma:300m","input":["договор содержит срок поставки","инструкция описывает обновление сервера","где указан срок поставки"],"truncate":false}'`. Сохраните полученный JSON как учебный результат и сверьте поле `model`, число элементов `embeddings` и одинаковую ненулевую длину каждого вектора. Документация допускает массив строк и возвращает массив векторов, но этот ответ нами не получен [s1](#src-s1)[s2](#src-s2)[s6](#src-s6).

По умолчанию `truncate` равно `true`; для индекса документов мы намеренно ставим `false`, чтобы слишком длинный фрагмент дал ошибку, а не тихую обрезку. При такой ошибке разбейте документ на фрагменты с известными границами и повторите индексацию; не меняйте модель только для запроса. Фиксируйте id фрагмента и исходное место в документе отдельно от вектора: числовой массив не является проверяемой цитатой [s2](#src-s2)[s1](#src-s1).

Для автоматической проверки формы ответа при сохранении JSON в локальном файле используйте `jq '{model, count:(.embeddings|length), dimensions:(.embeddings[0]|length)}'` с подачей сохранённого ответа на stdin. Здесь ожидаются три вектора одинаковой длины **если** ваш запрос выполнился; конкретную размерность мы не подставляем без фактического ответа модели. При ошибке `404` сначала проверьте точный тег в `ollama ls`, статус локального сервера и путь `/api/embed`; `/api/embeddings` из старых примеров не заменяет проверку текущего контракта [s2](#src-s2)[s4](#src-s4).

## Как проверить, найден ли подходящий фрагмент?

Пусть в `embeddings` идут сначала два фрагмента, затем вопрос. Рассчитайте для каждого фрагмента скалярное произведение с вектором вопроса: `score(d,q) = Σ_i d_i × q_i`; при документированной L2-нормализации это косинусная близость. Сортируйте только **эти два** фрагмента, затем откройте исходный текст наиболее близкого и вручную проверьте, отвечает ли он на вопрос. Оценка близости сама по себе не подтверждает истинности факта и не заменяет сравнения с первоисточником [s1](#src-s1)[s2](#src-s2).

Если установлен `jq`, сохранённый JSON с тремя векторами можно ранжировать так: `jq '.embeddings | .[2] as $q | .[0:2] | to_entries | map(.value as $v | {fragment:(.key+1),score:([range(0;($v|length)) as $i | $q[$i]*$v[$i]]|add)}) | sort_by(-.score)'`. `fragment: 1` или `2` здесь соответствует порядку двух исходных строк; **не** копируйте численный score из чужого компьютера как метрику качества. Формула и выражение проверены на синтетическом fixture для арифметики jq, но реальный embedding-ответ Modelium не получал [s1](#src-s1)[s2](#src-s2).

Для реальной проверки составьте несколько вопросов с ручной разметкой релевантного фрагмента, включая запрос, на который в документах нет ответа. Отдельно сохраните точные тексты/версии фрагментов, тег и digest модели, процедуру разбиения, ожидаемый фрагмент и ранжирование. Если нужный фрагмент не попал в первые результаты, ищите проблему в разбиении, языке/формулировке запроса, модели или данных; не выдавайте один удачный пример за измерение качества. Следующий шаг — [методика оценки локального RAG](/zhurnal/ocenka-kachestva-rag/) [s1](#src-s1)[s2](#src-s2).

## Почему клиент может получить ошибку или обратиться не туда?

- **Несовпадающий endpoint.** Нативный локальный Ollama API — `http://localhost:11434/api/embed`. Отдельный OpenAI-совместимый маршрут — `http://localhost:11434/v1/embeddings`; документация перечисляет поддерживаемые поля, но не делает эти пути одним и тем же. Прямой облачный `https://ollama.com/api` требует ключа, тогда как локальный запрос к установленному серверу — нет. Проверьте URL в клиенте прежде, чем добавлять токен или менять модель [s2](#src-s2)[s3](#src-s3)[s8](#src-s8).

- **Разные модели на входе и при поиске.** Если индекс записан одной моделью, а вопрос отправлен в другую, сравнение векторов теряет смысл. Повторите индексацию и запрос одним тегом и сохраните digest. Не смешивайте векторы даже тогда, когда их длина случайно совпала [s1](#src-s1)[s2](#src-s2).

- **Память и сеть.** `ollama ps` сообщает о загруженной модели и колонке `PROCESSOR`, но это наблюдение на вашем устройстве, не минимальные требования модели. Локальный API не доказывает, что другие программы не обращаются к облаку: Ollama позволяет отдельно отключить cloud-функции через `OLLAMA_NO_CLOUD=1` или `disable_ollama_cloud` в серверной конфигурации с перезапуском. Для строгого сценария проведите [сетевую проверку всего контура](/zhurnal/proverka-offline-kontura-ii/) [s4](#src-s4)[s5](#src-s5).

**Основной следующий шаг:** сохраните ранжирование на нескольких своих обезличенных вопросах, сопоставьте найденные фрагменты с исходным документом и переходите к [проверке качества RAG](/zhurnal/ocenka-kachestva-rag/). Этот материал описывает документированный API и протокол читателя; ни запуск модели, ни успешное нахождение фрагмента на стенде Modelium не заявлены [s1](#src-s1)[s2](#src-s2).

## Источники

1. [Ollama — Embeddings, закреплённый Git-документ](https://github.com/ollama/ollama/blob/42e911bc3d05798cad729cb474bf62f378cb2e26/docs/capabilities/embeddings.mdx) — получено 2026-10-04
2. [Ollama — OpenAPI schema, закреплённая ревизия](https://github.com/ollama/ollama/blob/42e911bc3d05798cad729cb474bf62f378cb2e26/docs/openapi.yaml) — получено 2026-10-04
3. [Ollama — API introduction, закреплённая ревизия](https://github.com/ollama/ollama/blob/42e911bc3d05798cad729cb474bf62f378cb2e26/docs/api/introduction.mdx) — получено 2026-10-04
4. [Ollama — CLI reference, закреплённая ревизия](https://github.com/ollama/ollama/blob/42e911bc3d05798cad729cb474bf62f378cb2e26/docs/cli.mdx) — получено 2026-10-04
5. [Ollama — FAQ: локальный сервер и облако, закреплённая ревизия](https://github.com/ollama/ollama/blob/42e911bc3d05798cad729cb474bf62f378cb2e26/docs/faq.mdx) — получено 2026-10-04
6. [Ollama Library — embeddinggemma:300m](https://ollama.com/library/embeddinggemma:300m) — получено 2026-10-04
7. [Ollama Library — qwen3-embedding](https://ollama.com/library/qwen3-embedding) — получено 2026-10-04
8. [Ollama — OpenAI-compatible embeddings, закреплённая ревизия](https://github.com/ollama/ollama/blob/42e911bc3d05798cad729cb474bf62f378cb2e26/docs/api/openai-compatibility.mdx) — получено 2026-10-04