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

Cambios en el API Gateway: v1.8 a v2.1

Resumen

El gateway de API ha obtenido nuevos despachadores de servicios WebSocket para consultas de incrustaciones, un nuevo punto final REST para el streaming de contenido de documentos, y ha experimentado un cambio significativo en el formato del cableado de Value a Term. El "servicio de objetos" se ha renombrado a "filas".

---

Nuevos Despachadores de Servicios WebSocket

Estos son nuevos servicios de solicitud/respuesta disponibles a través del multiplexador WebSocket en /api/v1/socket (con ámbito de flujo):

Clave de servicio	Descripción
document-embeddings	Consulta fragmentos de documentos por similitud de texto. La solicitud/respuesta utiliza los esquemas DocumentEmbeddingsRequest/DocumentEmbeddingsResponse.
row-embeddings	Consulta filas de datos estructurados por similitud de texto en campos indexados. La solicitud/respuesta utiliza los esquemas RowEmbeddingsRequest/RowEmbeddingsResponse.

Estos se unen al existente graph-embeddings dispatcher (que ya estaba presente en v1.8 pero puede que se haya actualizado).

Lista completa de despachadores de servicios de flujo WebSocket (v2.1)

Servicios de solicitud/respuesta (a través de /api/v1/flow/{flow}/service/{kind} o multiplexador 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

---

Nuevo Punto Final REST

Método	Ruta	Descripción
GET	/api/v1/document-stream	Transmite contenido de documentos desde la biblioteca como bytes brutos. Parámetros de consulta: user (obligatorio), document-id (obligatorio), chunk-size (opcional, predeterminado 1MB). Devuelve el contenido del documento con el codificado de transferencia en fragmentos, decodificado internamente en base64.

---

Servicio Renombrado: "objects" a "rows"

v1.8	v2.1	Notas
objects_query.py / ObjectsQueryRequestor	rows_query.py / RowsQueryRequestor	El esquema cambiado de ObjectsQueryRequest/ObjectsQueryResponse a RowsQueryRequest/RowsQueryResponse.
objects_import.py / ObjectsImport	rows_import.py / RowsImport	Despachador de importación para datos estructurados.

La clave del servicio WebSocket cambió de "objects" a "rows", y la clave del despachador de importación cambió de "objects" a "rows".

---

Cambio de Formato del Cable: Value a Term

La capa de serialización (serialize.py) se ha reescrito para utilizar el nuevo tipo Term en lugar del antiguo tipo Value.

Formato antiguo (v1.8 — Value)

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

• v: el valor (cadena)
• e: indicador booleano que indica si el valor es un URI

Formato nuevo (v2.1 — Term)

IRIs:

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

Literales:

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

Triples con comillas (RDF-star):

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

• t: discriminador de tipo — "i" (URI), "l" (literal), "r" (triple con comillas), "b" (nodo en blanco)
• La serialización ahora delega a TermTranslator y TripleTranslator de trustgraph.messaging.translators.primitives

Otros cambios en la serialización

Campo	v1.8	v2.1
Metadatos	metadata.metadata (subgrafo)	metadata.root (valor simple)
Entidad de incrustación	entity.vectors (plural)	entity.vector (singular)
Fragmento de incrustación de documento	chunk.vectors + chunk.chunk (texto)	chunk.vector + chunk.chunk_id (ID de referencia)

---

Cambios que Rompen

• Cambio de formato del cable Value a Term: Todos los clientes que envían/reciben triples, incrustaciones o contextos de entidad a través del gateway deben actualizar al nuevo formato Term.
• Cambio de nombre de objects a rows: Se ha modificado la clave del servicio WebSocket y la clave del despachador de importación.
• Cambio del campo de metadatos: metadata.metadata (un subgrafo serializado) reemplazado por metadata.root (un valor simple).
• Cambios en los campos de incrustación: vectors (plural) se convirtió en vector (singular); las incrustaciones de documentos ahora hacen referencia a chunk_id en lugar de a chunk de texto.
• Nuevo punto final /api/v1/document-stream: Aditivo, no rompe.