PrivateGPT: как пользоваться private AI API

PrivateGPT — это open-source Claude API-compatible слой для private AI-приложений поверх любого локального или self-hosted model server. Сам инференс не выполняет: подключается к серверу с /v1/chat/completions и /v1/models через OPENAI_API_BASE и даёт Messages API, ingestion файлов, retrieval с цитатами, tools и MCP. Фокус-ключ: privategpt. Канон: docs.privategpt.dev. Соседи: Ollama API, vLLM, Open WebUI, ИИ-автоматизация.

Новичку важно не путать слои: сначала поднимаете inference (Ollama / LM Studio / vLLM / llama.cpp), потом PrivateGPT как application API. Ниже — маршрут из Quickstart без выдуманных тарифов.

Слои стека: кто за что отвечает

Источник: docs.privategpt.dev Introduction + Quickstart + How it works (Claude API-compatible layer; OPENAI_API_BASE; PORT 8080; UI /ui; Ollama easiest start). Сверка: 2026-10-07. Цены облака в ₽ не фиксируем.

Установка и первый запуск

1. Поднимите OpenAI-compatible LLM-сервер. Самый простой старт — Ollama: ollama serve на порту 11434, плюс модель LLM и отдельно embedding-модель.
2. Установите PrivateGPT: Linux/Windows — uv tool install --python 3.11 --find-links https://wheels.privategpt.dev/packages/ "private-gpt[core]"; macOS — brew tap zylon-ai/tap && brew install private-gpt.
3. Запустите с env: OPENAI_API_BASE=http://localhost:<llm-port>/v1 и при необходимости OPENAI_EMBEDDING_API_BASE=…, команда private-gpt serve.
4. Откройте UI http://localhost:8080/ui и/или дерните API на :8080.

# Ollama (пример из Quickstart; id модели берите актуальный у себя)
ollama pull qwen3.5:35b
ollama pull mxbai-embed-large
ollama serve

# PrivateGPT → локальный inference
OPENAI_API_BASE=http://localhost:11434/v1 \
  OPENAI_EMBEDDING_API_BASE=http://localhost:11434/v1 \
  private-gpt serve

# Messages API (Anthropic-style)
curl http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3.5:35b", "messages": [{"role": "user", "content": "Объясни RAG коротко"}]}'

На старте конфиг не обязателен: PrivateGPT дергает GET /v1/models у inference и регистрирует модели сам. Профили settings-*.yaml и PGPT_PROFILES нужны, когда тюните tokenizer, context window и sampling.

Что даёт API сверх «просто чата»

• Messages — POST /v1/messages, streaming, count_tokens, validate, async.
• Knowledge — файлы/артефакты, PDF, retrieval с цитатами, embeddings.
• Tools — built-in (semantic search, tabular, SQL, web search/fetch, code execution, skills) и custom tools с JSON Schema.
• MCP — подключение remote MCP servers из запроса.

Это ближе к Claude application API, чем к сырому Chat Completions. Если нужен только чат в браузере без своей backend-логики — смотрите Open WebUI; если единый шлюз к облачным провайдерам — LiteLLM.

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

• Ждать, что PrivateGPT «заменит» Ollama: без inference-сервера serve не на чем строить.
• Путать UI на /ui с продуктом: UI — для теста; продукт — API.
• Забыть embedding endpoint, когда нужен retrieval, и удивляться пустому поиску по документам.
• Копировать старые гайды про «только локальный RAG-zip 2023 года» — актуальный канон на docs.privategpt.dev другой.
• Фиксировать рублевые тарифы облака в статье — здесь локальный/self-hosted контур.

FAQ: PrivateGPT

Вывод

PrivateGPT — слой приложения над вашим LLM-сервером: Claude-style Messages + files/tools/RAG на порту 8080. Старт: Ollama (или vLLM) → private-gpt[core] → private-gpt serve → UI/API. Когда нужна система обучения под интеграции — форматы на странице обучения.