RagFlow

RagFlow — self-hosted RAG-движок, ориентированный на документы: он разбирает PDF, DOCX, XLSX и презентации, нарезает их на осмысленные чанки, строит базу знаний и отвечает на вопросы со ссылками на источники. Подключать его к SpeShu.AI стоит там, где качество ответа упирается в разбор документа, а не в выбор модели — длинные таблицы, сканы, сложная вёрстка и многостраничные отчёты.

RagFlow работает через OpenAI-совместимый слой, поэтому от вас требуется ровно два значения: base_url = "https://speshu.ai/api/v1" и API-ключ. Никакой отдельной интеграции, специального SDK или адаптера не требуется.

В API SpeShu.AI нет эндпоинта эмбеддингов. RagFlow использует векторное хранилище по умолчанию, поэтому эмбеддинг-модель придётся зарегистрировать у другого провайдера, а SpeShu.AI оставить только для генерации ответа. Ниже показаны оба честных варианта: генерация через SpeShu.AI плюс эмбеддинги у отдельного провайдера, либо работа без эмбеддингов вовсе.

Установка RagFlow

RagFlow разворачивается официальным self-hosted compose-файлом. Требования по ресурсам высокие: от 4 ядер CPU и 16 ГБ RAM.

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker
docker compose -f docker-compose.yml up -d

UI поднимается на http://localhost:9380. Сборку выбранной версии фиксируйте явно (git checkout v0.x.y) — состав полей в настройках между релизами меняется.

Инструкции по установке меняются от версии к версии. Ориентируйтесь на раздел Installation в документации именно той сборки, которую вы зафиксировали.

Подготовка ключа и модели

Создайте ключ

Откройте speshu.ai/profile, войдите и создайте ключ в разделе API-ключей. Полное значение показывается один раз.

export SPESHU_API_KEY="sk-ваш-ключ"

Проверьте баланс

Запрос баланса не стоит токенов и сразу покажет, принят ли ключ.

cURL

curl -s https://speshu.ai/api/v1/balance \
  -H "Authorization: Bearer $SPESHU_API_KEY"

Возьмите идентификатор модели из каталога

Идентификаторы текстовых моделей не зашивайте в код: состав каталога меняется, и зашитая в конфиг строка рано или поздно отвалится с 404 model_not_found. Значение нужно один раз получить из API и положить в переменную окружения.

cURL

export SPESHU_MODEL=$(curl -s https://speshu.ai/api/v1/models \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  | jq -r '.data[0].id')
echo "$SPESHU_MODEL"

.data[0] — первый элемент, чтобы шаг был запускаемым. Для продакшена выбирайте модель по cost_completion, context_length и наличию зрения. Формат ответа — в разделе Модели и цены.

Дальше $SPESHU_MODEL — единственное место, где появляется идентификатор модели: он уходит в UI RagFlow, в .env и в переменную окружения контейнера. Перед регистрацией убедитесь, что модель отвечает:

Python

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://speshu.ai/api/v1",
    api_key=os.environ["SPESHU_API_KEY"],
)

response = client.chat.completions.create(
    model=os.environ["SPESHU_MODEL"],
    messages=[{"role": "user", "content": "Ответь одним словом."}],
)

print(response.choices[0].message.content)
print("списано:", response.usage.cost.total_cost, "₽")

Регистрация модели в RagFlow

Дальнейшие шаги зависят от версии RagFlow: подписи полей в UI менялись. Ориентируйтесь на раздел System Settings → Model в вашей сборке.

Вариант A: через интерфейс

Откройте Model в настройках системы.
Нажмите Add model и выберите фабрику OpenAI.
Заполните Model name ($SPESHU_MODEL), API key и Base URL.

Поле	Значение
Model name	`$SPESHU_MODEL` — идентификатор из `GET /api/v1/models`
API key	`sk-ваш-ключ`
Base URL	`https://speshu.ai/api/v1`

Сохраните модель и отметьте её как используемую по умолчанию в чате и агентах.

Если в вашей версии диалог фабрики OpenAI не содержит поля Base URL, вариант A не подходит — переходите к варианту B. Это не ошибка конфигурации, а разница между релизами.

Вариант B: через конфигурацию сервиса

Определение фабрики лежит в conf/llm_factories.json: у фабрики OpenAI есть поле base_url, у каждой модели — model_name, api_key, model_type и support_tools.

# базовый адрес задаётся в конфиге фабрики OpenAI
docker compose -f docker-compose.yml exec ragflow-server \
  python -c "import json;d=json.load(open('conf/llm_factories.json'));print(d['openai']['base_url'])"

Адрес можно задать и через переменные окружения в docker/.env — они перекрывают значения фабрики при старте контейнера:

cat >> .env <<'EOF'
OPENAI_BASE_URL=https://speshu.ai/api/v1
OPENAI_API_KEY=sk-ваш-ключ
EOF

docker compose -f docker-compose.yml up -d

Правка conf/llm_factories.json переживает обновление контейнера только до пересоздания тома с образом. Предпочтительнее переменные окружения: они сохраняются при обновлении и не требуют ручной правки при каждом релизе.

Модель эмбеддингов

Эмбеддинги RagFlow требует всегда: без зарегистрированной эмбеддинг-модели разбиение документа на чанки и индексация не запустятся. SpeShu.AI такой модели не предоставляет, поэтому зарегистрируйте её у другого провайдера — локальный inference, отдельный API или любой OpenAI-совместимый сервис с эндпоинтом /embeddings. Провайдер остаётся отдельной сущностью: свой ключ, своя фабрика, свой идентификатор модели. В RagFlow обе модели используются раздельно: эмбеддинг-модель обслуживает внутренний индекс, а зарегистрированная в SpeShu.AI — только генерацию ответа и вызов инструментов.

Первый рабочий пример

Официальный Python-клиент RagFlow (ragflow-python) работает с самим RAG-движком: он создаёт датасет, загружает документ, запускает разбор и выполняет поиск. Внутри этих вызовов RagFlow обращается к LLM через SpeShu.AI по настройкам из предыдущего шага.

pip install ragflow-python
export RAGFLOW_API_KEY="ragflow-ваш-ключ"   # токен RagFlow из UI, не ключ SpeShu.AI

Python

import os

from ragflow_client import RAGFlowClient

client = RAGFlowClient(
    api_key=os.environ["RAGFLOW_API_KEY"],
    base_url="http://localhost:9380",
)

dataset = client.create_dataset(name="Регламенты")

# путь к локальному файлу на диске, где запущен скрипт
dataset.upload_documents(file_paths=["./reglament.pdf"])
dataset.parse()

for chunk in dataset.retrieval(question="Какой срок согласования договора?"):
    print(chunk["content_with_weight"])
    print("источник:", chunk["document_key"])

Набор классов и методов клиента менялся между версиями RagFlow, а параметры конструктора — между его релизами. Приведённый вариант соответствует ветке ragflow-python 0.x; в более ранних сборках используйте HTTP-эндпоинты RagFlow напрямую, сверяясь с документацией вашей версии.

Ключи в этом примере не взаимозаменяемы: RAGFLOW_API_KEY — токен доступа к вашему инстансу RagFlow, SPESHU_API_KEY — ключ платформы, который RagFlow подставляет сам при обращении к модели.

Что дальше подробнее

Потоковая передача. RagFlow отдаёт ответ по частям, а внизу показывает ссылки на источники. Формат кадров, маркер [DONE] и кадр со списанием разобраны на странице Потоковая передача. Учтите, что RagFlow ограничивает длину генерации: если ответ не успевает, снижайте объём контекста, а не отключайте поток. Вызов функций. Если вы зарегистрировали модель с поддержкой инструментов (флаг support_tools в фабрике), RagFlow может вызывать MCP-серверы и встроенные агенты. Формат tools[] и цикл вызова — в разделе Вызов функций. Структурированный вывод. Для извлечения полей из документов RagFlow просит модель вернуть JSON по схеме. Схемы, json_schema и обработка отказов разобраны в разделе Структурированный вывод.

Генерация изображений, видео и аудио в этом API живёт в отдельных эндпоинтах и не входит в OpenAI-совместимый слой чата, поэтому штатный конвейер RagFlow через них не проходит. Если такие задачи нужны, вызывайте их напрямую — разбор в разделе Создание медиа-задачи.

Расход

RagFlow сам не считает деньги: списание происходит на стороне SpeShu.AI и возвращается в usage.cost.total_cost каждого ответа. Суммируйте это поле по всем запросам агента — длинный RAG-сеанс с несколькими итерациями инструментов легко съедает заметную часть баланса. Подробнее — в разделе Тарификация и оплата.

Типичные проблемы

404 на /api/v1/chat/completions, RagFlow пишет «connection refused»

В Base URL указан https://speshu.ai или https://speshu.ai/api — без сегмента /v1. Открытый каталог моделей работает без ключа, поэтому по нему это не видно: проверяйте адрес именно на чат-эндпоинте.

В Base URL стоит адрес с завершающим слэшем

Строка вида https://speshu.ai/api/v1/ даёт пути вида //chat/completions, и прокси между RagFlow и API отвечает 404. Уберите слэш в конце.

401 invalid_api_key при первом же вопросе к базе знаний

Ключ не доехал: в RagFlow он часто лежит в отдельном поле фабрики, а не в переменных окружения контейнера. Проверьте, что значение содержит префикс sk- целиком, без кавычек и переносов строки, и что оно записано именно в ту фабрику, к которой привязана модель.

404 model_not_found на генерации, хотя модель видна в UI

Идентификатор в поле Model name устарел или обрезан. Возьмите его заново из GET /api/v1/models и подставьте как есть — вместе со слэшем в именах вида группа/имя.

Разбор документа останавливается, эмбеддингов нет

SpeShu.AI не отдаёт эмбеддинги, и зарегистрированная у него модель не может использоваться как эмбеддинг-модель RagFlow. Заведите отдельную эмбеддинг-модель у другого провайдера и перезапустите разбор документа.

Ответ приходит целиком, без постепенного текста

Обычно это не поломка API, а буферизация на стороне RagFlow или UI-фронтенда. Отдельно убедитесь, что сам вызов доходит до /chat/completions с stream: true — формат кадров описан в разделе Потоковая передача.

Всё остальное

Полная таблица кодов, три формата ошибок и цикл повторов — на странице Ошибки. Таймауты и квоты — в разделе Лимиты.

Что дальше

Начало работы

Практический маршрут от ключа до первого ответа

Модели и цены

Каталог, owned_by и цены за миллион токенов

Потоковая передача

SSE, [DONE] и кадр со списанием

Ошибки

Коды, форматы и что с ними делать

Начало работы

Возможности моделей

Генерация медиа

Фреймворки

Базы данных

Агенты и редакторы

No-code и автоматизация

Установка RagFlow

Подготовка ключа и модели

Регистрация модели в RagFlow

Вариант A: через интерфейс

Вариант B: через конфигурацию сервиса

Модель эмбеддингов

Первый рабочий пример

Что дальше подробнее

Расход

Типичные проблемы

Что дальше

Начало работы

Модели и цены

Потоковая передача

Ошибки

​Установка RagFlow

​Подготовка ключа и модели

​Регистрация модели в RagFlow

​Вариант A: через интерфейс

​Вариант B: через конфигурацию сервиса

​Модель эмбеддингов

​Первый рабочий пример

​Что дальше подробнее

​Расход

​Типичные проблемы

​Что дальше

Начало работы

Модели и цены

Потоковая передача

Ошибки

Установка RagFlow

Подготовка ключа и модели

Регистрация модели в RagFlow

Вариант A: через интерфейс

Вариант B: через конфигурацию сервиса

Модель эмбеддингов

Первый рабочий пример

Что дальше подробнее

Расход

Типичные проблемы

Что дальше