TNWS AI

Гайд · TNWS AI

Как загрузить файл как blob в Ollama API с проверкой SHA-256

WindowsmacOSLinux#нейросети#API#Ollama API
8 мин—

Считаем digest, отправляем бинарный файл в POST /api/blobs/:digest, проверяем 201 Created и подтверждаем blob независимым HEAD-запросом.

Задача и практический результат

Цель этого гайда — загрузить GGUF или другой файл модели на Ollama server как content-addressed blob и доказать совпадение переданного SHA-256. Результат считается готовым только при наличии машинно проверяемого доказательства: конкретного типа, HTTP-статуса, поля JSON, элемента истории или счётчика вызовов. Красивый ответ модели и отсутствие исключения сами по себе успех не подтверждают.

Названия методов и полей сверены 12 сентября 2026 года по официальной документации Ollama API. В материал не включены неподтверждённые цены, лимиты, региональная доступность и результаты производительности: они не нужны для выполнения описанного контракта. При обновлении пакета или сервера запустите тесты повторно.

Подтверждённый контракт

  • Загрузка выполняется POST /api/blobs/:digest.
  • Тело запроса — байты файла, а digest в URL — ожидаемый SHA-256.
  • Успешное создание возвращает HTTP 201 Created.
  • Если digest не соответствует содержимому, официальный контракт предусматривает HTTP 400 Bad Request.
  • После загрузки существование blob можно независимо проверить HEAD-запросом.

Каждый пункт выше превращается в отдельную проверку. Не объединяйте их в одну расплывчатую проверку вроде «запрос прошёл». Например, HTTP 200 не заменяет проверку status в теле, а подсказка type checker не заменяет runtime-валидацию. Такой подход особенно важен в агентных системах, где модельный ответ, tool call и локальная бизнес-логика имеют разные жизненные циклы.

Что подготовить

  • отдельное тестовое окружение и зафиксированную версию зависимости или сервера;
  • обезличенный вход без API-ключей, cookie, реальных реквизитов и персональных данных;
  • fake tool или model stub, если сценарий способен вызвать внешний side effect;
  • лог событий с точными полями, но без полного пользовательского диалога;
  • автоматическую проверку, завершающую процесс ошибкой при несовпадении контракта.

До запуска определите, какой эффект допустим. Проверка чтения может обращаться к тестовому endpoint, но публикацию, оплату, удаление и отправку сообщений следует заменить счётчиком или sandbox-реализацией. Retry и resume нельзя тестировать на реальной операции, которую опасно выполнить дважды.

Пошаговая настройка

  1. Посчитайте SHA-256 потоково, не загружая большой файл целиком в строку или JSON.
  2. Откройте бинарный ReadStream и отправьте его телом POST; для Node fetch укажите duplex:"half".
  3. Признайте успех только при статусе 201. Статус 400 рассматривайте как нарушение целостности.
  4. После POST выполните HEAD по тому же digest и потребуйте статус 200.

После каждого шага фиксируйте наблюдаемый результат. Если проверяется порядок, храните массив событий. Если тип — используйте isinstance или строгий runtime-флаг. Если HTTP API — проверяйте и status code, и обязательные поля тела. Если состояние сервера — подтверждайте его отдельным read-only endpoint.

Готовый минимальный пример

Сохраните код в отдельный файл. Заполнители в угловых скобках нельзя отправлять как реальные digest или идентификаторы. Пример намеренно останавливается при несовпадении: тихое продолжение превратило бы ошибку в ложный успех.

import { createHash } from "node:crypto";
import { createReadStream } from "node:fs";

const path = "model.gguf";
const hash = createHash("sha256");
for await (const chunk of createReadStream(path)) hash.update(chunk);
const digest = "sha256:" + hash.digest("hex");
const url = "http://localhost:11434/api/blobs/" + digest;

const upload = await fetch(url, {
  method: "POST",
  body: createReadStream(path),
  duplex: "half",
});
if (upload.status !== 201) {
  throw new Error("upload status " + upload.status);
}
const check = await fetch(url, {method: "HEAD"});
if (check.status !== 200) throw new Error("blob not confirmed");
console.log(digest);

Для Python запускайте файл в virtualenv проекта. JavaScript-пример сохраните как .mjs и используйте Node.js с глобальным fetch. Не смешивайте глобальную и проектную версии SDK. Перед первым интеграционным запросом выведите только безопасные параметры: endpoint, имя тестовой модели и версию, но никогда токен.

Реалистичный вход

Вход: файл model.gguf; digest вычисляется самим скриптом, а не копируется из имени файла или чужого манифеста.

Ожидаемый результат

POST возвращает 201, последующий HEAD — 200. Выводится тот же digest, который использован в URL. При несовпадении содержимого и digest ожидается 400.

Запишите это ожидание в assert или явный throw. Естественно-языковой текст может меняться, поэтому тестируйте стабильный инвариант. Для типов это класс объекта, для approval — число interruptions и executions, для blob — точный status, для create — финальное поле success и независимое присутствие новой записи.

Обязательный негативный тест

После вычисления digest измените файл и отправьте новые байты по старому URL. Сервер должен отклонить запрос; тест не должен принимать любой 2xx или пропускать HEAD.

Негативный сценарий запускайте в том же окружении. Он должен сломать ровно проверяемое условие, а не весь стенд. Сетевая недоступность не равна 404, TypeError не равен отказу модели, новый Runner не равен resume, а старое имя в каталоге не доказывает успешную пересборку. Эти различия следует выразить кодом.

Копируемый prompt для ревью

Проверь загрузчик blob: digest вычисляется до отправки, тело бинарное, не JSON, ожидается именно 201, 400 трактуется как mismatch, после загрузки выполняется HEAD 200.

Ответ верни таблицей: проверяемое условие, доказательство из кода или лога, PASS/FAIL, минимальное исправление. Не додумывай версии, статусы и результаты. Если доказательства нет, ставь FAIL.

Прикладывайте к prompt минимальный код и очищенный лог. После ответа вручную откройте указанные строки: языковая модель может принять комментарий за работающую проверку. Prompt помогает организовать ревью, но не заменяет запуск тестов.

Как проверить результат независимо

Сделайте таблицу минимум из трёх строк: штатный ввод, намеренно ошибочный ввод и пограничное значение. Для каждой укажите ожидаемую ветку, наблюдаемый признак и фактический результат. Если используется provider stub, считайте модельные обращения. Если tool fake — считайте исполнения. Если API — сохраните status и минимальный JSON без чувствительных данных.

Повторите тест дважды. Второй запуск не должен неожиданно удваивать side effect, использовать старый объект или принимать кешированный результат за новый. Для операций создания выбирайте уникальное тестовое имя и после проверки сверяйте именно его. Для content-addressed blobs сравнивайте полный SHA-256, а не начало строки.

В CI фиксируйте версии и exit code. Не сохраняйте сырой prompt, полный raw response или пути пользователя, если они содержат данные. Для диагностики достаточно response id, типа события, статуса и контрольного digest — при условии, что каждый из них получен из реального ответа, а не создан локально для красоты.

Типичные ошибки

Проверяется только счастливый путь

Такой тест может никогда не войти в нужную ветку. Добавьте управляемое несовпадение типа, отсутствующий digest, отказ approval или изменённую историю. Убедитесь, что тест падает именно по ожидаемой причине.

Разные идентификаторы смешиваются

Response ID, trace ID, tool call ID, SHA-256 digest и имя модели служат разным задачам. Не подменяйте один другим и не генерируйте локальное значение там, где нужен идентификатор сервера.

Успех объявляется слишком рано

Ответ transport-уровня ещё не подтверждает бизнес-состояние. После POST проверьте обязательное поле, после create — каталог моделей, после approval — счётчик tool, после преобразования — runtime-тип.

Ошибка версии маскируется fallback-кодом

Если метода или параметра нет, зафиксируйте несовместимость. Универсальный except, возвращающий «готово», делает документацию недостоверной и скрывает регрессию.

Чек-лист финальной проверки

  • Title, slug и тема не повторяют существующую публикацию.
  • Точные имена API сверены по официальному источнику 12 сентября 2026 года.
  • В коде нет секретов и реальных пользовательских данных.
  • Успешная ветка проверяет точный тип, status, поле или состояние.
  • Негативная ветка действительно активирует противоположный исход.
  • Fake tool или stub считает обращения, если возможен side effect.
  • Не смешиваются response ID, trace ID, call ID и digest.
  • Повторный запуск не создаёт ложный или двойной результат.
  • Ограничения не заменены выдуманными метриками.
  • После обновления версии тест можно запустить повторно.

Ограничения

Руководство проверяет один технический контракт, а не безопасность всей системы, качество модели или экономическую эффективность. Конкретные задержки, расход памяти, размер файла и точность зависят от модели и инфраструктуры; без воспроизводимого измерения их нельзя превращать в обещание.

Учитывайте доверительную границу. Локальный Ollama endpoint при публикации в сеть требует собственной защиты. Approval в SDK не заменяет серверную авторизацию. Освобождение ссылок Python не гарантирует мгновенное уменьшение RSS. Типизированный output не гарантирует истинность извлечённых данных. Эти риски проверяются отдельными слоями.

FAQ

Почему в статье нет цен и универсальных лимитов?

Они не участвуют в данном контракте и меняются независимо. Если стоимость нужна вашему проекту, сверяйте официальный pricing в день расчёта с валютой и единицей тарификации.

Можно ли считать HTTP 200 достаточной проверкой?

Нет. Используйте точный статус из официального контракта и проверяйте обязательные поля или состояние через независимый endpoint.

Зачем сохранять версию?

Имена методов и поведение меняются. Версия позволяет воспроизвести результат и отличить ошибку интеграции от изменения SDK или сервера.

Можно ли доверить финальную проверку нейросети?

Нет. Она может провести ревью структуры, но фактический PASS должен выставлять исполняемый тест или проверенный ответ API.

Первоисточник

Материал написан самостоятельно по контракту первоисточника. Примеры используют тестовые идентификаторы и не являются результатами скрытого бенчмарка.

Читайте также

ГайдыWindowsmacOS12 сентября 2026

Как квантовать FP16-модель через Ollama API /api/create

Создаём отдельный q4_K_M-вариант из FP16-модели, проверяем progress, финальный success и не перезаписываем исходное имя.

8 мин 
ГайдыWindowsmacOS12 сентября 2026

Как подключить LoRA adapter при создании модели через Ollama API

Загружаем adapter как blob, передаём словарь adapters в /api/create, проверяем success и сохраняем базовую модель без изменений.

8 мин 
ГайдыWindowsmacOS12 сентября 2026

Как проверить наличие blob в Ollama API через HEAD-запрос

Вычисляем SHA-256, вызываем HEAD /api/blobs/:digest и различаем подтверждённые статусы 200 и 404 перед созданием модели.

8 мин 

Подбор

Какую нейросеть выбрать

Пройти опрос

Комментарии

Пока тихо. Скажите первое слово