Включение Ассистента в распределенной инсталляции

Как работать c Ассистентом

Инструкция по настройке SSO-аутентификации (Stroma, SWA) — в документе описана настройка SSO-аутентификации по протоколу OpenID Connect (OIDC) в Мессенджере и Почте VK WorkSpace при помощи сервиса Stroma в составе Мессенджера.

WS Assistant — это сервис для умного поиска информации в Мессенджере VK WorkSpace. С его помощью вы можете задавать вопросы и находить релевантные чаты, обсуждения и сообщения. При работе Ассистент использует права доступа пользователя.

Какие задачи решает Ассистент:

1. Поиск по сообщениям — найдет в переписке нужные факты, решения и договоренности. Поиск работает не по вхождению слов, а по семантическому смыслу.
2. Работа с содержимым переписки — агент получает списки чатов и сообщений и дальше работает с ними уже на стороне LLM. Отсюда разные сценарии: собрать сообщения, на которые вы не успели ответить, разложить обсуждение на смысловые части и ответить на конкретные вопросы собеседников, категоризировать тикеты в поддержку и разобраться в вопросе по всей истории переписки.
3. Подготовка черновиков сообщений — отформатирует сообщение и упомянет участников.
4. Поиск нужного человека — найдет сотрудника, покажет его должность.

Ограничения Ассистента:

1. Работает на базе большой языковой модели и может ошибаться.
2. Может допускать неточности при работе с числами и датами.
3. Не работает с файлами, но вы можете выслать содержимое файла в чат.
4. Не работает с почтовыми сервисами.
5. Не помогает с вопросами:
   • требующими доступа к закрытым системам и ресурсам.
   • выходящими за рамки корпоративных инструментов.
   • требующими отдельной авторизации.
6. Обрабатывает запросы только на русском языке.

WS Assistant включает в себя агента для поиска и обработки данных и LLM модель VK. Если вы используете LLM модель от VK, для работы сервиса необходим доступ в интернет — для доставки LLM модели VK на серверы заказчика.

После включения сервиса в десктоп-приложении VK WorkSpace появится мини-приложение WS Assistant, а по адресу assistant.vkt.*/mcp станет доступен MCP-сервер для поиска по сообщениям (подключается к Claude Code, Codex и другим MCP-клиентам).

При отсутствии доступа в интернет или в связи с политиками безопасности компании вы можете подключить собственную LLM модель, которая будет доступна в приложении VK WorkSpace в списке мини-аппов в панели сервисов.

Документ предназначен для использования администраторами организации.

Необходимые пререквизиты перед включением Ассистента:

1. Установлена распределенная инсталляция Мессенджера по инструкции. На этапе установки добавлены серверы под Ассистент, для серверов добавлена роль ansible-vkteams-cluster.
2. Настроена интеграция Мессенджера с Почтой, Диском или Доской по инструкции.
3. Включена SSO-аутентификация по инструкции. Запомните вывод команды sso token assistant, он понадобится вам дальше.

Если вы используете LLM модель от VK, вам потребуется:

1. Имя и токен клиента — получите их у представителей VK.

2. Доступ в интернет. Для работы WS Assistant необходим доступ до ресурса https://as-updater.vkteam.ru, с которого происходит скачивание LLM моделей VK. При отсутствии доступа в интернет вы можете использовать собственную LLM модель.

WS Assistant использует три нейросети, у каждой — своя работа:

• LLM — читает вопрос, решает, где искать, и пишет ответ.
• Модель эмбеддингов — преобразует каждое сообщение в набор чисел (вектор), чтобы можно было искать сообщения по смыслу, а не только по точным словам.
• Реранкер — берет то, что нашел поиск, и сортирует документы по их релевантности к запросу пользователя. Каждая нейросеть — это отдельный сервис со своим адресом (URL).

1. Все сервисы должны иметь OpenAI-совместимый API. Ассистент обращается:
   • к LLM — по протоколу OpenAI Chat Completions (эндпоинт /v1/chat/completions);
   • к модели эмбеддингов — по эндпоинту /v1/embeddings;
   • к реранкеру — через эндпоинт /v1/score.
2. Проще всего запустить модели в vLLM — именно так они работают в поставке VK. Для LLM подойдет и другой OpenAI-совместимый сервер (например, Ollama свежих версий) или внешний OpenAI-совместимый API-сервис.
3. LLM должна поддерживать:
   • Вызов инструментов (tool calling / function calling). Без этого Ассистент не сможет пользоваться поиском по сообщениям и просто не будет работать.
   • Контекст не меньше 32K токенов: во время поиска Ассистент передает модели десятки тысяч токенов за один запрос. На моделях с коротким контекстом качество ответов резко падает.
   • Два режима получения ответов от языковой модели:
     • синхронный (обычный).
     • потоковый (streaming) — ответ передается по частям через Server‑Sent Events (SSE).
4. Эмбеддер должен поддерживать возврат ответа в двух форматах: в виде массива чисел с плавающей точкой (encoding_format: "float") либо в виде строки Base64 (encoding_format: "base64").
5. Реранкер должен предоставлять контракт эндпоинта /v1/score (не ограничиваясь общей совместимостью с OpenAI API). Запрос должен включать параметры model, строку запроса text_1, массив документов text_2 и формат кодирования encoding_format: "float32". В ответе по полю data[].score должна возвращаться одна оценка релевантности на каждый документ в том же порядке, в котором документы были переданы во входном массиве.
6. При настройке конфигурации в Установщике во всех полях URL указывайте адрес вместе с /v1 на конце, как в примерах в шаге 3, подраздел «Если вы используете собственную LLM модель».
7. Все модели должны возвращать ответ с кодом 200 на метод GET /v1/models. Тело ответа неважно.

Единственный поддерживаемый вариант — Qwen/Qwen3-Embedding-0.6B. Альтернатив в данной версии нет.

Работа WS Assistant протестирована на следующих моделях:

• Qwen3.5-9B-FP8 — локально в vLLM. Модель из поставки VK: лучший баланс качества, скорости и размера. Рекомендуемый вариант для локального запуска.
• GPT-5.6 Terra (внешний API) — качество ответов на уровне Qwen3.5-9B, при этом отвечает в несколько раз быстрее и расходует меньше токенов. Только если политика компании допускает внешние API.
• Claude Sonnet 5 (внешний API) — качество немного выше Qwen3.5-9B и GPT-5.6 Terra, скорость сопоставима с Terra. Только если политика компании допускает внешние API.
• Qwen3.5-122B-A10B — лучшее качество среди всех проверенных моделей. Этот вариант подходит в случае, если качество важнее всего.
• gemma-4-26B-A4B-it — самая быстрая из протестированных при качестве на уровне Qwen3.5-9B.

Также возможно использовать любую другую OpenAI-совместимую модель с поддержкой tool calling, но ее необходимо протестировать на ваших типовых запросах.

Проверенные варианты:

• mixedbread-ai/mxbai-rerank-large-v2 (1.5B) — рекомендуемый вариант, используется в поставке VK: лучший баланс качества и скорости.
• llama-nemotron-rerank-1b-v2 (1B) — высокое качество, но реранжирование заметно медленнее на старых GPU с Compute Capability ≤ 7.5. Если у вас современные GPU с Compute Capability ≥ 8, то это достойный вариант.
• bge-reranker-v2-m3 (0.6B) — быстрая и качественная, но стабильно быстро работает только на vLLM 0.10.1.1 с XFormers, на других версиях замедляется в разы.

Оценки качества и скорости получены на внутренних датасетах VK. На ваших данных и вашем оборудовании результаты могут отличаться — при замене модели проверяйте качество ответов на своих типовых запросах.

1. Перейдите в веб-интерфейс установщика VK WorkSpace — в адресной строке браузера укажите адрес http://server-ip-address:8888. Если перейти по этому адресу не удается, убедитесь, что firewall был отключен.

2. В правом верхнем углу нажмите на значок i → Продукты.

3. Перейдите в раздел Мессенджер и активируйте опции WS Assistant и Nomini:

   

4. Нажмите на кнопку Сохранить.

Перейдите в раздел Проекты → wsAssistant → idm_form и заполните поля:

• Тип авторизации IDM — укажите SWA или SSO.
• Client secret IDM — укажите токен мини-аппа, который был создан при настройке SSO-аутентификации (вывод команды sso token assistant).

Нажмите на кнопку Сохранить настройки.

1. Перейдите в раздел Проекты → wsAssistant → inference_form и заполните поля:

   

   Если вы используете LLM модель от VK

   • API-ключ сервиса эмбеддингов — поле заполняется самостоятельно при использовании LLM модели VK.
   • URL сервиса эмбеддингов — http://vllm-vkrage-embed.llm-inference.svc.cluster.local:8000/v1
   • Модель LLM — lovedheart/Qwen3.5-9B-FP8.
   • URL LLM — http://vllm-vkrage-think.llm-inference.svc.cluster.local:8000/v1
   • API-ключ reranker — поле заполняется самостоятельно при использовании LLM модели VK.
   • Модель reranker — mxbai-rerank-large-v2.
   • URL reranker — http://vllm-vkrage-rerank.llm-inference.svc.cluster.local:8000/v1

   Если вы используете собственную LLM модель

   • URL сервиса эмбеддингов — адрес API сервиса, на котором запущена модель эмбеддингов. Пример: http://my-embed-server:8000/v1.

   • API-ключ сервиса эмбеддингов — ключ доступа, если ваш сервис требует авторизацию. Если сервис поднят без ключа, оставьте поле пустым.

   • Модель LLM — имя вашей языковой модели, точно в том виде, в каком оно задано в вашем сервисе. Это значение Ассистент подставляет в поле model каждого запроса. Для vLLM имя задается флагом --served-model-name. Пример: lovedheart/Qwen3.5-9B-FP8.

   • URL LLM — адрес OpenAI-совместимого API вашей LLM. Пример: http://my-llm-server:8000/v1.

   • API-ключ LLM — ключ доступа к LLM, если сервис требует авторизацию. Иначе оставьте поле пустым.

   • Модель reranker — имя модели реранкера, правила те же, что для поля Модель LLM. Пример: mixedbread-ai/mxbai-rerank-large-v2.

   • URL reranker — адрес API сервиса с реранкером (vLLM). Пример: http://my-rerank-server:8000/v1.

   • API-ключ reranker — ключ доступа к реранкеру, если сервис требует авторизацию. Иначе оставьте поле пустым.

2. Нажмите на кнопку Сохранить настройки.

Пропустите этот шаг, если используете собственную LLM модель.

Данная настройка требуется только при использовании моделей от VK. Сервис доставки обновлений (LLMUpdater) скачивает модели VK с сервера обновлений и устанавливает их — для этого и нужны имя клиента, токен и адрес https://as-updater.vkteam.ru.

1. Перейдите в раздел Проекты → llmUpdater → LLMUpdater Proxy и заполните поля:

   

   • Имя клиента и Токен клиента — получите их у представителей VK или у вашего провайдера.

   • Адрес сервера обновлений — https://as-updater.vkteam.ru

2. Нажмите на кнопку Сохранить настройки и запустите автоматическую установку.

Этот шаг является опциональным: он относится к GPU-сервисам локального запуска (vLLM Embedding / Rerank / Thinking Model) и нужен только при использовании моделей из поставки VK. Если вы используете собственные модели, пропустите его.

По умолчанию сервис настроен под 1 000 пользователей.

Если необходимо увеличить размеры каждого GPU сервиса, перейдите Проекты → llmInference → llmInference и увеличьте количество реплик в каждом из сервисов:

• vLLM Embedding Model.
• vLLM Rerank Model
• vLLM Thinking Model.

Количество реплик рассчитывается индивидуально для каждого заказчика. Для получения точных значений обратитесь к представителям VK или своему менеджеру.

Нажмите на кнопку Сохранить настройки.

Этот шаг является опциональным: он относится к GPU-сервисам локального запуска (vLLM Embedding / Rerank / Thinking Model) и нужен только при использовании моделей из поставки VK. Если вы используете собственные модели, пропустите его.

Вы можете включить технологию MIG, если ваша видеокарта из поколения Ampere, Hopper или Blackwell — это обеспечит полную изоляцию процессов с жестким выделением видеопамяти. Перед включением опции обязательно проконсультируйтесь с представителем VK Tech.

1. Перейдите Проекты → llmInference → hami и активируйте опцию Включить MIG:

   

2. В поле Узлы для MIG укажите имя сервера с GPU. Имя сервера должно быть указано, как в установщике VK WorkSpace.

3. Нажмите на кнопку Сохранить настройки.

Нажмите на логотип VK WorkSpace левом верхнем углу и далее на кнопку Добавить → Распределение продуктов Helm:

Выберите кластер K8s, namespace указывать не обязательно. Нажмите на кнопку Сохранить:

Запустите автоматическую установку — нажмите на кнопку Play рядом с общей строкой состояния в верхней части экрана:

Подтвердите запуск автоматической установки, нажав на кнопку Запустить. Перед запуском автоматической установки оставьте включенными все проверки.

В зависимости от этапа установки будет меняться цвет индикатора:

• Серый — в ожидании начала генерации;
• Синий — в процессе генерации;
• Желтый — шаг будет повторен (автоматически);
• Красный — ошибка.

Ожидайте завершения установки. Пока процесс идет, рядом со строкой состояния будет отображаться красная кнопка Stop. Дождитесь завершения установки.

Если в процессе установки и настройки системы происходят изменения конфигурации, некоторые задачи могут потребовать повторного выполнения. Для повторного запуска необходимо нажать на кнопку Play в общей строке состояния в верхней части экрана или рядом с названием конкретного контейнера.

Когда установка будет завершена, соответствующий статус отобразится в строке состояния.

Включение WS Assistant считается завершенным. После завершения установки в десктоп-приложении VK WorkSpace появится мини-приложение WS Assistant, а по адресу assistant.vkt.*/mcp станет доступен MCP-сервер для поиска по сообщениям (подключается к Claude Code, Codex и другим MCP-клиентам).