mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26:21 +02:00
109 lines
4.1 KiB
Markdown
109 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` 端点**: 添加的，非破坏性。
|