> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yahont.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Основные понятия

> Основные понятия и терминология для работы с API Yahont

## Действия и MCP

> **Действия**
>
> Действия (в бэкенде их также называют инструментами) — это функции,
> которые ваши агенты могут выполнять для взаимодействия с внешними системами и сервисами.
> Они расширяют возможности ваших агентов за пределы языковой модели.
>
> Встроенные действия:
>
> | Название | Описание | Требует настройки | Варианты поставщиков |
> | - | - | - | - |
> | Внутренний поиск | Поиск по проиндексированным документам и базе знаний вашей организации | Да | Встроен, компоненты можно заменять |
> | Веб-поиск | Поиск информации в интернете в реальном времени и по текущим событиям | Да | Srezai, Exa, Serper, Brave, Google PSE, SearXNG, Tavily, Firecrawl |
> | Выполнение кода | Выполнение кода на Python, анализ данных и построение визуализаций | Нет | Встроено |
> | Генерация изображений | Создание изображений по текстовому описанию с помощью ИИ-моделей | Да | OpenAI, Azure OpenAI, Google Vertex AI, RouterAI, Polza.AI |
> | Агент по коду <sup>Beta</sup> | Исследует публичный репозиторий GitHub и отвечает на вопросы о нём | Да (по умолчанию отключён) | Встроен |
>
> Пользовательские действия:
>
> * **Интеграции API**: подключение к внешним REST API
> * **Операции с базами данных**: запросы и обновление баз данных
> * **Автоматизация рабочих процессов**: запуск бизнес-процессов
> * **Операции с файлами**: чтение, запись и обработка файлов
>
> Собственные пользовательские действия можно определить в панели администратора с помощью спецификации OpenAPI.

> **MCP**
>
> Model Context Protocol (MCP) — открытый стандарт,
> который позволяет ИИ-ассистентам безопасно получать доступ к внешним источникам данных и инструментам.
> Yahont можно настроить как клиент MCP, чтобы управляемо взаимодействовать с внешними системами, базами данных и API.
>
> Ключевые возможности MCP:
>
> * **Доступ к внешним данным**: подключение к базам данных, API и файловым системам
> * **Аутентификация**: сквозная передача OAuth для безопасного доступа к вашему MCP-серверу.

> **(Расширенное) Пользовательские встроенные действия**
>
> Иногда нужно больше контроля над действием, чем позволяет пользовательское действие.
> Поскольку Yahont — проект с открытым исходным кодом, вы можете расширить встроенные действия по своему усмотрению!
>
> Шаблоны встроенных действий находятся в `backend/onyx/tools/tool_implementations` в [репозитории
> Yahont](https://github.com/pipedude/yahont-ce).
>
> > [!WARNING]
> >
> > Расширение кодовой базы не рекомендуется большинству пользователей. Прежде чем начать,
> > обратитесь к нам за поддержкой в [Telegram](https://t.me/yahont_ai)!

## Агенты

> **Агенты**
>
> Агенты — это ИИ-ассистенты с пользовательскими инструкциями, действиями и доступом к данным,
> расширяющие возможности базовой LLM.
>
> > [!NOTE]
> >
> > Термины *ассистент* (Assistant) и *агент* (Agent)
> > в Yahont используются как взаимозаменяемые и обозначают одно и то же понятие.
>
> **Встроенные агенты:**
>
> * `id: 0` Search Agent — использует инструмент поиска, чтобы отвечать на вопросы по вашей базе знаний
> * `id: -1` General Agent — базовый чат без инструментов (обычный чат с LLM)
> * `id: -2` Paraphrase Agent — использует инструмент поиска и цитирует точные фрагменты из источников
> * `id: -3` Art Agent — создаёт изображения и визуальный контент
>
> Вы можете создавать собственных агентов в панели администратора или через API.
>
> **Для большинства конечных точек чата нужен ID агента**
>
> Чтобы найти ID агента, можно:
>
> * Использовать конечную точку API `GET /persona` для вывода списка всех агентов
> * В панели администратора: открыть агента и посмотреть первое число в URL

## Чат

> **Потоковые ответы чата**
>
> Система ответов чата использует пакетную архитектуру для доставки ответов пользователям в реальном времени.
> Вместо ожидания полного ответа система разбивает взаимодействие в чате на отдельные пакеты,
> которые передаются постепенно.
>
> Каждый пакет имеет единую структуру, определённую классом `Packet`:
>
> ```python theme={null}
> class Packet(BaseModel):
>   ind: int        # Sequential index for ordering
>   obj: PacketObj  # The actual content including type of packet
> ```
>
> **Поток передачи:**
>
> * Запрос чата запускает процесс потоковой передачи
> * В зависимости от нужных операций создаются пакеты разных типов
>   (рассуждения, вызовы инструментов, ответ ИИ, документы, цитаты и т. д.)
> * Пакеты отправляются с последовательными индексами, чтобы сохранить порядок
> * Фронтенд обрабатывает пакеты в реальном времени и обновляет интерфейс
> * Пакет `OverallStop` сигнализирует о завершении

> **Базовые пакеты сообщений**
>
> **MessageStart и MessageDelta**
>
> Эти пакеты составляют основу системы потоковых ответов:
>
> * **MessageStart**:
>   начинает новое сообщение с начальным содержимым и итоговыми найденными документами (если они есть)
> * **MessageDelta**: доставляет текст по мере его создания

> **Управляющие пакеты**
>
> **Управление сессией и разделами**
>
> Управляющие пакеты определяют ход и жизненный цикл потоковой передачи:
>
> * **OverallStop**: сигнализирует о конце всей сессии потоковой передачи
> * **SectionEnd**: отмечает завершение типа пакетов (рассуждения, сообщение, цитаты и т. д.)

> **Пакеты инструментов**
>
> Ответы инструментов передаются так же, как основной ответ сообщения.
>
> **Инструменты поиска**
>
> * SearchToolStart и SearchToolDelta обрабатывают операции поиска документов
>
> **Генерация изображений**
>
> * ImageGenerationToolStart,
>   ImageGenerationToolDelta и ImageGenerationToolHeartbeat управляют созданием изображений ИИ
>
> **Пользовательские инструменты**
>
> * CustomToolStart и CustomToolDelta используются для MCP и пользовательских действий
>
> Пакет start сигнализирует о начале ответа инструмента. Пакеты delta передают результаты по мере их появления.

> **Пакеты рассуждений**
>
> Все шаги рассуждений передаются потоком, чтобы фронтенд мог отображать их по мере обработки. Пакеты рассуждений,
> как правило, отправляются первыми.
>
> * **ReasoningStart**: начинает раздел рассуждений
> * **ReasoningDelta**: передаёт процесс рассуждений ИИ

> **Пакеты цитат**
>
> Пакеты цитат связывают ID цитат с ID документов.
>
> * **CitationStart**: начинает результаты цитирования
> * **CitationDelta**: доставляет цитаты и ссылки на источники

## Коннекторы

> [!TIP]
>
> Когда вы видите термин *коннектор* в Yahont или в другом месте этой документации,
> обычно имеются в виду *ConnectorCredentialPairs*

> **Коннекторы**
>
> `Connectors` в Yahont определяют данные, которые вы хотите индексировать
>
> * `name`: на самом деле не отображается в интерфейсе, если задано `ConnectorCredentialPairMetadata:name`
> * `source`: к какой системе подключаться (см. раскрывающийся блок `DocumentSource` ниже)
> * `input_type`: как `Connector` получает данные (см. раскрывающийся блок `InputType` ниже)
> * `connector_specific_config`: настройки конкретного источника, например пути к папкам или каналы. Ожидаемые настройки конкретного коннектора смотрите в [`/backend/onyx/connectors`](https://github.com/pipedude/yahont-ce/tree/main/backend/onyx/connectors).
> * `refresh_freq`: как часто проверять новое или обновлённое содержимое, в секундах
> * `prune_freq`: как часто удалять устаревшее содержимое из Yahont, в секундах
> * `indexing_start`: необязательная дата и время начала индексации
>
> ```python Python theme={null}
> class ConnectorBase(BaseModel):
>   name: str
>   source: DocumentSource
>   input_type: InputType
>   connector_specific_config: dict[str, Any]
>   refresh_freq: int | None = None
>   prune_freq: int | None = None
>   indexing_start: datetime | None = None
> ```

> **Учётные данные**
>
> `Credentials` содержат сведения для аутентификации, необходимые для доступа к источникам данных. Это ключи API,
> токены OAuth, персональные токены доступа (PAT) или учётные данные сервисных аккаунтов,
> которые позволяют Yahont безопасно подключаться к вашим внешним системам.
>
> Типы `Credentials`:
>
> * **Ключи API**: простая аутентификация по токену
> * **Токены OAuth**: делегированная авторизация с возможностью обновления
> * **Сервисные аккаунты**: аутентификация между машинами
> * **Персональные токены доступа**: учётные данные доступа конкретного пользователя

> **ConnectorCredentialPairs**
>
> За кулисами `Connectors` и `Credentials` объединяются в `ConnectorCredentialPair` (CC-pair,
> пара «коннектор — учётные данные»). CC-pair — это активное подключение,
> которое может синхронизировать данные из ваших внешних источников в Yahont.
> Именно CC-pair вы видите и обслуживаете на странице администратора `Connectors`.
>
> Возможности CC-pair:
>
> * **Активные подключения**: синхронизация данных между источником и Yahont в реальном времени
>
> * **Мониторинг состояния**: отслеживание работоспособности и производительности синхронизации
>
> * **Управление доступом**: определение, кто может видеть данные из этого подключения
>
> * **Управление конфигурацией**: изменение настроек синхронизации и учётных данных
>
> > [!WARNING]
> >
> > Если вы создаёте `Connectors` через API, их нужно связать с `Credential` (CC-pair), чтобы они стали активными!

> **ConnectorCredentialPairMetadata**
>
> `ConnectorCredentialPairMetadata` определяет настройки конфигурации и доступа для CC-pair.
>
> Параметры конфигурации:
>
> * `name`: необязательное отображаемое имя CC-pair (переопределяет имя `Connector`)
> * `access_type`: кто может получать доступ к данным этого CC-pair (см. раскрывающийся блок `AccessType` ниже)
> * `auto_sync_options`: необязательная конфигурация параметров автоматической синхронизации
> * `groups`: список ID групп, имеющих доступ к этому CC-pair
>
> ```python Python theme={null}
> class ConnectorCredentialPairMetadata(BaseModel):
>   name: str | None = None
>   access_type: AccessType
>   auto_sync_options: dict[str, Any] | None = None
>   groups: list[int] = Field(default_factory=list)
> ```

## Документы

> **DocumentBase**
>
> `DocumentBase` — основная структура, используемая в Yahont для хранения данных документов и управления ими.
> Обратите внимание, что эмбеддинги хранятся в OpenSearch отдельно.
>
> * `id`: уникальный идентификатор. Создаётся Yahont, если не указан
>
> * `sections`: список разделов содержимого (см. `TextSection` и `ImageSection`)
>
> * `source`: система, из которой получен документ (см. `DocumentSource`)
>
> * `semantic_identifier`: отображается в интерфейсе как название документа
>
> * `metadata`: произвольные `string` или `list[string]`, которые будут сохранены как теги документа
>
> * `doc_updated_at`: метка времени UTC последнего обновления документа
>
> * `chunk_count`: число фрагментов, на которые документ разбивается для обработки
>
> * `primary_owners`: метаданные о людях, связанных с документом
>
> * `secondary_owners`: метаданные о людях, связанных с документом
>
> * `title`: используется для поиска (по умолчанию `semantic_identifier`, если не указан)
>
> * `from_ingestion_api`: получен ли этот документ через Ingestion API
>
> * `additional_info`: информация, специфичная для коннектора, которая может понадобиться другим частям кода
>
> * `external_access`: данные синхронизации прав (только Enterprise Edition)
>
> > [!NOTE]
> >
> > Ingestion API расширяет определение DocumentBase полем `cc_pair_id`,
> > чтобы автоматически связать документ с CC-pair.
>
> ```python Python expandable theme={null}
> class DocumentBase(BaseModel):
>   """Used for Yahont ingestion api, the ID is inferred before use if not provided"""
>
>   id: str | None = None
>   sections: list[TextSection | ImageSection]
>   source: DocumentSource | None = None
>   semantic_identifier: str
>   metadata: dict[str, str | list[str]]
>
>   doc_updated_at: datetime | None = None
>   chunk_count: int | None = None
>
>   primary_owners: list[BasicExpertInfo] | None = None
>   secondary_owners: list[BasicExpertInfo] | None = None
>   title: str | None = None
>   from_ingestion_api: bool = False
>   additional_info: Any = None
>
>   external_access: ExternalAccess | None = None
> ```

> **DocumentSource**
>
> `DocumentSource` — перечисление, определяющее допустимые источники документа.
> Для загрузки файлов в Ingestion API и программного создания `Connectors` нужно указать `DocumentSource`.
>
> ```python Python expandable theme={null}
> class DocumentSource(str, Enum):
>   INGESTION_API = "ingestion_api"     # Special case, document passed in via Yahont APIs without specifying a source type
>   SLACK = "slack"
>   WEB = "web"
>   GOOGLE_DRIVE = "google_drive"
>   GMAIL = "gmail"
>   REQUESTTRACKER = "requesttracker"
>   GITHUB = "github"
>   GITBOOK = "gitbook"
>   GITLAB = "gitlab"
>   GURU = "guru"
>   BOOKSTACK = "bookstack"
>   CONFLUENCE = "confluence"
>   JIRA = "jira"
>   SLAB = "slab"
>   PRODUCTBOARD = "productboard"
>   FILE = "file"
>   NOTION = "notion"
>   ZULIP = "zulip"
>   LINEAR = "linear"
>   HUBSPOT = "hubspot"
>   DOCUMENT360 = "document360"
>   GONG = "gong"
>   GOOGLE_SITES = "google_sites"
>   ZENDESK = "zendesk"
>   LOOPIO = "loopio"
>   DROPBOX = "dropbox"
>   SHAREPOINT = "sharepoint"
>   TEAMS = "teams"
>   SALESFORCE = "salesforce"
>   DISCOURSE = "discourse"
>   AXERO = "axero"
>   CLICKUP = "clickup"
>   MEDIAWIKI = "mediawiki"
>   WIKIPEDIA = "wikipedia"
>   ASANA = "asana"
>   S3 = "s3"
>   R2 = "r2"
>   GOOGLE_CLOUD_STORAGE = "google_cloud_storage"
>   OCI_STORAGE = "oci_storage"
>   XENFORO = "xenforo"
>   NOT_APPLICABLE = "not_applicable"
>   DISCORD = "discord"
>   FRESHDESK = "freshdesk"
>   FIREFLIES = "fireflies"
>   EGNYTE = "egnyte"
>   AIRTABLE = "airtable"
>   HIGHSPOT = "highspot"
>
>   IMAP = "imap"
>
>   # Special case just for integration tests
>   MOCK_CONNECTOR = "mock_connector"
> ```

> **TextSection**
>
> `TextSection` — часть документа в Yahont.
>
> * `text`: собственно текстовое содержимое раздела
> * `link`: необязательный URL, к которому относится этот текстовый раздел или из которого он получен
>
> ```python Python theme={null}
> class TextSection(Section):
>   text: str
>   link: str | None = None
> ```

> **ImageSection**
>
> `ImageSection` — изображение, извлечённое из документа в Yahont.
>
> * `image_file_id`: UUID файла изображения, хранящегося в файловом хранилище Yahont
> * `text`: необязательное текстовое описание или подпись к изображению
> * `link`: необязательный URL, к которому относится этот раздел изображения или из которого он получен
>
> ```python Python theme={null}
> class ImageSection(Section):
>   image_file_id: str
>   text: str | None = None
>   link: str | None = None
> ```

> **AccessType**
>
> `AccessType` определяет, кто может получать доступ к данным `Connector` в Yahont.
>
> * `PUBLIC`: все пользователи Yahont могут получать доступ к данным этого `Connector`
> * `PRIVATE`: только пользователь, создавший `Connector`, и указанные группы могут получать доступ к данным этого `Connector`
> * `SYNC`: значение SYNC можно задать только `Connectors` с поддержкой синхронизации прав. `Connector` будет синхронизировать права доступа с исходной системой.
>
> ```python Python theme={null}
> class AccessType(str, Enum):
>   PUBLIC = "public"
>   PRIVATE = "private"
>   SYNC = "sync"
> ```

> **InputType**
>
> `InputType` определяет, как `Connector` получает данные из исходной системы.
>
> * `LOAD_STATE`: однократная загрузка данных из источника
> * `POLL`: непрерывный опрос источника на наличие новых данных (начинается с полной загрузки)
> * `EVENT`: для большинства `Connectors` не реализовано
> * `SLIM_RETRIEVAL`: для `Connectors` с синхронизацией прав
>
> ```python Python theme={null}
> class InputType(str, Enum):
>   LOAD_STATE = "load_state"
>   POLL = "poll"
>   EVENT = "event"
>   SLIM_RETRIEVAL = "slim_retrieval"
> ```

## Дальнейшие шаги

> **[Руководство: индексирование файлов с помощью Ingestion API](/developers/guides/index_files_ingestion_api)**
>
> Узнайте, как индексировать файлы с помощью Ingestion API

> **[Руководство: отправка сообщения чата](/developers/guides/chat_new_guide)**
>
> Простой пример программной отправки сообщения


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.