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.1 KiB
Markdown
108 lines
4.1 KiB
Markdown
---
|
||
layout: default
|
||
title: "API 网关变更：v1.8 到 v2.1"
|
||
parent: "Chinese (Beta)"
|
||
---
|
||
|
||
# API 网关变更：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 网关新增了用于嵌入查询的 WebSocket 服务分发器，新增了 REST 串流端点，用于文档内容，并进行了重要的 Wire 格式变化，从 `Value` 变为 `Term`。 "对象" 服务已被重命名为 "行"。
|
||
|
||
---
|
||
|
||
## 新的 WebSocket 服务分发器
|
||
|
||
这些是可通过 WebSocket 多路复用器 `/api/v1/socket` (范围限定) 访问的新请求/响应服务：
|
||
|
||
| 服务键 | 描述 |
|
||
|---|---|
|
||
| `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 端点
|
||
|
||
| 方法 | 路径 | 描述 |
|
||
|---|---|---|
|
||
| `GET` | `/api/v1/document-stream` | 从库中流式传输文档内容为原始字节。 查询参数：`user` (必需), `document-id` (必需), `chunk-size` (可选, 默认 1MB)。 返回文档内容，通过内部进行 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"`。
|
||
|
||
---
|
||
|
||
## Wire 格式变化： Value 为 Term
|
||
|
||
`serialize.py` (序列化层) 已重写为使用新的 `Term` 类型，而不是旧的 `Value` 类型。
|
||
|
||
### 旧格式 (v1.8 - `Value`)
|
||
|
||
```json
|
||
{"v": "http://example.org/entity", "e": true}
|
||
```
|
||
|
||
- `v`: 值 (字符串)
|
||
- `e`: 布尔标志，指示值是否为 URI
|
||
|
||
### 新格式 (v2.1 - `Term`)
|
||
|
||
IRI:
|
||
```json
|
||
{"t": "i", "i": "http://example.org/entity"}
|
||
```
|
||
|
||
字面量：
|
||
```json
|
||
{"t": "l", "v": "some text", "d": "datatype-uri", "l": "en"}
|
||
```
|
||
|
||
带引号的三元组 (RDF-star):
|
||
```json
|
||
{"t": "r", "r": {"s": {...}, "p": {...}, "o": {...}}}
|
||
```
|
||
|
||
- `t`: 类型区分值 — `"i"` (IRI), `"l"` (字面量), `"r"` (带引号的三元组), `"b"` (空节点)
|
||
- 序列化现在委托给 `trustgraph.messaging.translators.primitives` 中的 `TermTranslator` 和 `TripleTranslator`
|
||
|
||
### 其他序列化更改
|
||
|
||
| 字段 | v1.8 | v2.1 |
|
||
|---|---|---|
|
||
| 元数据 | `metadata.metadata` (子图) | `metadata.root` (简单值) |
|
||
| 图嵌入实体 | `entity.vectors` (复数) | `entity.vector` (单数) |
|
||
| 文档嵌入块 | `chunk.vectors` + `chunk.chunk` (文本) | `chunk.vector` + `chunk.chunk_id` (ID 引用) |
|
||
|
||
---
|
||
|
||
## 破坏性变更
|
||
|
||
- **Value 到 Term 的 Wire 格式**: 任何通过网关发送/接收三元组、嵌入或实体上下文的客户端都必须更新为新的 Term 格式。
|
||
- **objects 到 rows 的重命名**: WebSocket 服务键和导入键已更改。
|
||
- **元数据字段更改**: `metadata.metadata` (序列化的子图) 已被 `metadata.root` (简单值) 替换。
|
||
- **嵌入字段更改**: `vectors` (复数) 变为 `vector` (单数)；文档嵌入现在引用 `chunk_id` 而不是内联 `chunk` 文本。
|
||
- **新的 `/api/v1/document-stream` 端点**: 添加的，非破坏性。
|