mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26:21 +02:00
240 lines
7 KiB
Markdown
240 lines
7 KiB
Markdown
|
---
|
|||
|
|
layout: default
|
|||
|
|
title: "OpenAPI 规范 - 技术规范"
|
|||
|
|
parent: "Chinese (Beta)"
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# OpenAPI 规范 - 技术规范
|
|||
|
|
|
|||
|
|
> **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.
|
|||
|
|
|
|||
|
|
## 目标
|
|||
|
|
|
|||
|
|
创建一个全面的、模块化的 OpenAPI 3.1 规范，用于 TrustGraph REST API 网关，该规范应：
|
|||
|
|
记录所有 REST 接口
|
|||
|
|
使用外部 `$ref` 以实现模块化和可维护性
|
|||
|
|
直接映射到消息转换器代码
|
|||
|
|
提供准确的请求/响应模式
|
|||
|
|
|
|||
|
|
## 权威来源
|
|||
|
|
|
|||
|
|
API 由以下内容定义：
|
|||
|
|
**消息转换器**: `trustgraph-base/trustgraph/messaging/translators/*.py`
|
|||
|
|
**分派器管理器**: `trustgraph-flow/trustgraph/gateway/dispatch/manager.py`
|
|||
|
|
**端点管理器**: `trustgraph-flow/trustgraph/gateway/endpoint/manager.py`
|
|||
|
|
|
|||
|
|
## 目录结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
openapi/
|
|||
|
|
├── openapi.yaml # Main entry point
|
|||
|
|
├── paths/
|
|||
|
|
│ ├── config.yaml # Global services
|
|||
|
|
│ ├── flow.yaml
|
|||
|
|
│ ├── librarian.yaml
|
|||
|
|
│ ├── knowledge.yaml
|
|||
|
|
│ ├── collection-management.yaml
|
|||
|
|
│ ├── flow-services/ # Flow-hosted services
|
|||
|
|
│ │ ├── agent.yaml
|
|||
|
|
│ │ ├── document-rag.yaml
|
|||
|
|
│ │ ├── graph-rag.yaml
|
|||
|
|
│ │ ├── text-completion.yaml
|
|||
|
|
│ │ ├── prompt.yaml
|
|||
|
|
│ │ ├── embeddings.yaml
|
|||
|
|
│ │ ├── mcp-tool.yaml
|
|||
|
|
│ │ ├── triples.yaml
|
|||
|
|
│ │ ├── objects.yaml
|
|||
|
|
│ │ ├── nlp-query.yaml
|
|||
|
|
│ │ ├── structured-query.yaml
|
|||
|
|
│ │ ├── structured-diag.yaml
|
|||
|
|
│ │ ├── graph-embeddings.yaml
|
|||
|
|
│ │ ├── document-embeddings.yaml
|
|||
|
|
│ │ ├── text-load.yaml
|
|||
|
|
│ │ └── document-load.yaml
|
|||
|
|
│ ├── import-export/
|
|||
|
|
│ │ ├── core-import.yaml
|
|||
|
|
│ │ ├── core-export.yaml
|
|||
|
|
│ │ └── flow-import-export.yaml # WebSocket import/export
|
|||
|
|
│ ├── websocket.yaml
|
|||
|
|
│ └── metrics.yaml
|
|||
|
|
├── components/
|
|||
|
|
│ ├── schemas/
|
|||
|
|
│ │ ├── config/
|
|||
|
|
│ │ ├── flow/
|
|||
|
|
│ │ ├── librarian/
|
|||
|
|
│ │ ├── knowledge/
|
|||
|
|
│ │ ├── collection/
|
|||
|
|
│ │ ├── ai-services/
|
|||
|
|
│ │ ├── common/
|
|||
|
|
│ │ └── errors/
|
|||
|
|
│ ├── parameters/
|
|||
|
|
│ ├── responses/
|
|||
|
|
│ └── examples/
|
|||
|
|
└── security/
|
|||
|
|
└── bearerAuth.yaml
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 服务映射
|
|||
|
|
|
|||
|
|
### 全局服务 (`/api/v1/{kind}`)
|
|||
|
|
`config` - 配置管理
|
|||
|
|
`flow` - 流生存周期
|
|||
|
|
`librarian` - 文档库
|
|||
|
|
`knowledge` - 知识核心
|
|||
|
|
`collection-management` - 集合元数据
|
|||
|
|
|
|||
|
|
### 托管于流的服务 (`/api/v1/flow/{flow}/service/{kind}`)
|
|||
|
|
|
|||
|
|
**请求/响应:**
|
|||
|
|
`agent`, `text-completion`, `prompt`, `mcp-tool`
|
|||
|
|
`graph-rag`, `document-rag`
|
|||
|
|
`embeddings`, `graph-embeddings`, `document-embeddings`
|
|||
|
|
`triples`, `objects`, `nlp-query`, `structured-query`, `structured-diag`
|
|||
|
|
|
|||
|
|
**发布/订阅:**
|
|||
|
|
`text-load`, `document-load`
|
|||
|
|
|
|||
|
|
### 导入/导出
|
|||
|
|
`/api/v1/import-core` (POST)
|
|||
|
|
`/api/v1/export-core` (GET)
|
|||
|
|
`/api/v1/flow/{flow}/import/{kind}` (WebSocket)
|
|||
|
|
`/api/v1/flow/{flow}/export/{kind}` (WebSocket)
|
|||
|
|
|
|||
|
|
### 其他
|
|||
|
|
`/api/v1/socket` (WebSocket 多路复用)
|
|||
|
|
`/api/metrics` (Prometheus)
|
|||
|
|
|
|||
|
|
## 方案
|
|||
|
|
|
|||
|
|
### 第一阶段：设置
|
|||
|
|
1. 创建目录结构
|
|||
|
|
2. 创建主 `openapi.yaml` 文件，包含元数据、服务器、安全配置
|
|||
|
|
3. 创建可重用组件（错误、通用参数、安全方案）
|
|||
|
|
|
|||
|
|
### 第二阶段：通用模式
|
|||
|
|
创建在服务间共享的模式：
|
|||
|
|
`RdfValue`, `Triple` - RDF/三元组结构
|
|||
|
|
`ErrorObject` - 错误响应
|
|||
|
|
`DocumentMetadata`, `ProcessingMetadata` - 元数据结构
|
|||
|
|
通用参数：`FlowId`, `User`, `Collection`
|
|||
|
|
|
|||
|
|
### 第三阶段：全球服务
|
|||
|
|
对于每个全球服务（配置、流程、库管理员、知识、集合管理）：
|
|||
|
|
1. 在 `paths/` 中创建路径文件。
|
|||
|
|
2. 在 `components/schemas/{service}/` 中创建请求模式。
|
|||
|
|
3. 创建响应模式。
|
|||
|
|
4. 添加示例。
|
|||
|
|
5. 从主文件 `openapi.yaml` 中引用。
|
|||
|
|
|
|||
|
|
### 第四阶段：流程托管服务
|
|||
|
|
对于每个流程托管服务：
|
|||
|
|
1. 在 `paths/flow-services/` 中创建路径文件。
|
|||
|
|
2. 在 `components/schemas/ai-services/` 中创建请求/响应模式。
|
|||
|
|
3. 在适用情况下，添加流媒体标志文档。
|
|||
|
|
4. 从主文件 `openapi.yaml` 中引用。
|
|||
|
|
|
|||
|
|
### 第五阶段：导入/导出 & WebSocket
|
|||
|
|
1. 文档核心导入/导出端点。
|
|||
|
|
2. 文档 WebSocket 协议模式。
|
|||
|
|
3. 文档流程级别的导入/导出 WebSocket 端点。
|
|||
|
|
|
|||
|
|
### 第六阶段：验证
|
|||
|
|
1. 使用 OpenAPI 验证工具进行验证。
|
|||
|
|
2. 使用 Swagger UI 进行测试。
|
|||
|
|
3. 验证所有翻译器是否已覆盖。
|
|||
|
|
|
|||
|
|
## 字段命名约定
|
|||
|
|
|
|||
|
|
所有 JSON 字段使用 **kebab-case**：
|
|||
|
|
`flow-id`, `blueprint-name`, `doc-limit`, `entity-limit`, 等。
|
|||
|
|
|
|||
|
|
## 创建模式文件
|
|||
|
|
|
|||
|
|
对于 `trustgraph-base/trustgraph/messaging/translators/` 中的每个翻译器：
|
|||
|
|
|
|||
|
|
1. **读取翻译器 `to_pulsar()` 方法** - 定义请求模式。
|
|||
|
|
2. **读取翻译器 `from_pulsar()` 方法** - 定义响应模式。
|
|||
|
|
3. **提取字段名称和类型**。
|
|||
|
|
4. **创建 OpenAPI 模式**，包含：
|
|||
|
|
字段名称（kebab-case）。
|
|||
|
|
类型（字符串、整数、布尔值、对象、数组）。
|
|||
|
|
必需字段。
|
|||
|
|
默认值。
|
|||
|
|
描述。
|
|||
|
|
|
|||
|
|
### 示例映射过程
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# From retrieval.py DocumentRagRequestTranslator
|
|||
|
|
def to_pulsar(self, data: Dict[str, Any]) -> DocumentRagQuery:
|
|||
|
|
return DocumentRagQuery(
|
|||
|
|
query=data["query"], # required string
|
|||
|
|
user=data.get("user", "trustgraph"), # optional string, default "trustgraph"
|
|||
|
|
collection=data.get("collection", "default"), # optional string, default "default"
|
|||
|
|
doc_limit=int(data.get("doc-limit", 20)), # optional integer, default 20
|
|||
|
|
streaming=data.get("streaming", False) # optional boolean, default false
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
对应于：
|
|||
|
|
|
|||
|
|
```yaml
|
|||
|
|
# components/schemas/ai-services/DocumentRagRequest.yaml
|
|||
|
|
type: object
|
|||
|
|
required:
|
|||
|
|
- query
|
|||
|
|
properties:
|
|||
|
|
query:
|
|||
|
|
type: string
|
|||
|
|
description: Search query
|
|||
|
|
user:
|
|||
|
|
type: string
|
|||
|
|
default: trustgraph
|
|||
|
|
collection:
|
|||
|
|
type: string
|
|||
|
|
default: default
|
|||
|
|
doc-limit:
|
|||
|
|
type: integer
|
|||
|
|
default: 20
|
|||
|
|
description: Maximum number of documents to retrieve
|
|||
|
|
streaming:
|
|||
|
|
type: boolean
|
|||
|
|
default: false
|
|||
|
|
description: Enable streaming responses
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 流式响应
|
|||
|
|
|
|||
|
|
支持流式传输的服务会返回带有 `end_of_stream` 标志的多个响应：
|
|||
|
|
`agent`, `text-completion`, `prompt`
|
|||
|
|
`document-rag`, `graph-rag`
|
|||
|
|
|
|||
|
|
在每个服务的响应模式中记录此模式。
|
|||
|
|
|
|||
|
|
## 错误响应
|
|||
|
|
|
|||
|
|
所有服务都可以返回：
|
|||
|
|
```yaml
|
|||
|
|
error:
|
|||
|
|
oneOf:
|
|||
|
|
- type: string
|
|||
|
|
- $ref: '#/components/schemas/ErrorObject'
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
其中，`ErrorObject` 指的是：
|
|||
|
|
```yaml
|
|||
|
|
type: object
|
|||
|
|
properties:
|
|||
|
|
type:
|
|||
|
|
type: string
|
|||
|
|
message:
|
|||
|
|
type: string
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 参考文献
|
|||
|
|
|
|||
|
|
翻译人员：`trustgraph-base/trustgraph/messaging/translators/`
|
|||
|
|
调度映射：`trustgraph-flow/trustgraph/gateway/dispatch/manager.py`
|
|||
|
|
终端路由：`trustgraph-flow/trustgraph/gateway/endpoint/manager.py`
|
|||
|
|
服务摘要：`API_SERVICES_SUMMARY.md`
|