trustgraph/docs/api-gateway-changes-v1.8-to-v2.1.ru.md

layout	title	parent
default	Изменения в API Gateway: v1.8 до v2.1	Russian (Beta)

Изменения в API Gateway: v1.8 до v2.1

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

Обзор

API Gateway получил новые диспетчеры WebSocket для запросов на основе встраивания, новый REST-endpoint для потоковой передачи содержимого документов, и претерпел значительные изменения в формате представления данных, перейдя с Value на Term. Сервис "objects" был переименован в "rows".

---

Новые диспетчеры WebSocket

Это новые сервисы запросов/ответов, доступные через WebSocket-мультиплексор по адресу /api/v1/socket (с фокусом на flow):

Ключ сервиса	Описание
document-embeddings	Запросы на фрагменты документов по текстовому сходству. Используются схемы DocumentEmbeddingsRequest/DocumentEmbeddingsResponse.
row-embeddings	Запросы на структурированные данные по текстовому сходству по индексированным полям. Используются схемы RowEmbeddingsRequest/RowEmbeddingsResponse.

Эти диспетчеры работают вместе с существующим диспетчером graph-embeddings (который уже был в v1.8, но мог быть обновлен).

Полный список диспетчеров WebSocket (v2.1)

Сервисы запросов/ответов (через /api/v1/flow/{flow}/service/{kind} или WebSocket-мультиплексор):

• agent, text-completion, prompt, mcp-tool
• graph-rag, document-rag
• embeddings, graph-embeddings, document-embeddings
• triples, rows, nlp-query, structured-query, structured-diag
• row-embeddings

---

Новый REST Endpoint

Метод	Путь	Описание
GET	/api/v1/document-stream	Потоковая передача содержимого документов из библиотеки в виде сырых байтов. Параметры запроса: user (обязательно), document-id (обязательно), chunk-size (необязательно, значение по умолчанию 1MB). Возвращает содержимое документа в коде transfer encoding, который декодируется из base64 внутри.

---

Переименованный сервис: "objects" в "rows"

v1.8	v2.1	Примечания
objects_query.py / ObjectsQueryRequestor	rows_query.py / RowsQueryRequestor	Схема изменена с ObjectsQueryRequest/ObjectsQueryResponse на RowsQueryRequest/RowsQueryResponse.
objects_import.py / ObjectsImport	rows_import.py / RowsImport	Импорт для структурированных данных.

Ключ WebSocket-сервиса изменился с "objects" на "rows", а ключ импорт-диспатчера аналогично — с "objects" на "rows".

---

Изменение формата представления данных: Value на Term

Слой сериализации (serialize.py) был переписан для использования нового типа Term вместо старого типа Value.

Старый формат (v1.8 — Value)

{"v": "http://example.org/entity", "e": true}

• v: значение (строка)
• e: булевский флаг, указывающий, является ли значение URI

Новый формат (v2.1 — Term)

URI:

{"t": "i", "i": "http://example.org/entity"}

Литералы:

{"t": "l", "v": "some text", "d": "datatype-uri", "l": "en"}

Тройки, указанные в кавычках (RDF-star):

{"t": "r", "r": {"s": {...}, "p": {...}, "o": {...}}}

• t: дискриминатор типа — "i" (URI), "l" (литерал), "r" (тройка), "b" (blank node)
• Сериализация теперь делегируется TermTranslator и TripleTranslator из trustgraph.messaging.translators.primitives

Другие изменения в сериализации

Поле	v1.8	v2.1
Metadata	metadata.metadata (подграфа)	metadata.root (простое значение)
Graph embeddings entity	entity.vectors (множественное)	entity.vector (одиночное)
Document embeddings chunk	chunk.vectors + chunk.chunk (текст)	chunk.vector + chunk.chunk_id (ссылка на ID)

---

Изменения, требующие внимания

• Формат представления данных Value в Term: Все клиенты, отправляющие/получающие тройки, встраивания или контексты сущностей через gateway, должны обновиться до нового формата Term.
• Переименование объектов в rows: Изменился ключ WebSocket-сервиса и ключ импорт-диспатчера.
• Изменение поля metadata: metadata.metadata (сериализованная подграфа) заменено на metadata.root (простое значение).
• Изменения полей embeddings: vectors (множественное) стало vector (одиночное); теперь встраивания документов ссылаются на chunk_id вместо inline chunk.
• Новый endpoint /api/v1/document-stream: Дополнительный, не является "breaking".