mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 00:46:22 +02:00
8954fa3ad7
Native CLI i18n: The TrustGraph CLI has built-in translation support that dynamically loads language strings. You can test and use different languages by simply passing the --lang flag (e.g., --lang es for Spanish, --lang ru for Russian) or by configuring your environment's LANG variable. Automated Docs Translations: This PR introduces autonomously translated Markdown documentation into several target languages, including Spanish, Swahili, Portuguese, Turkish, Hindi, Hebrew, Arabic, Simplified Chinese, and Russian.
108 lines
4.8 KiB
Markdown
108 lines
4.8 KiB
Markdown
---
|
|
layout: default
|
|
title: "Cambios en el API Gateway: v1.8 a v2.1"
|
|
parent: "Spanish (Beta)"
|
|
---
|
|
|
|
# Cambios en el API Gateway: v1.8 a 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.
|
|
|
|
## 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`)
|
|
|
|
```json
|
|
{"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:
|
|
```json
|
|
{"t": "i", "i": "http://example.org/entity"}
|
|
```
|
|
|
|
Literales:
|
|
```json
|
|
{"t": "l", "v": "some text", "d": "datatype-uri", "l": "en"}
|
|
```
|
|
|
|
Triples con comillas (RDF-star):
|
|
```json
|
|
{"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.
|