OGX 0.5 版本发布详解：API 一致性重构、OpenAI 兼容性提升与连接器生态扩展

OGX 0.5 版本发布详解：API 一致性重构、OpenAI 兼容性提升与连接器生态扩展

【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx

OGX（Open GenAI Stack）0.5 是继 0.4 之后的一次大规模演进版本，核心围绕 API 一致性、OpenAI 规范对齐、Provider 能力增强与整体架构重构展开。本文基于仓库内 RELEASE_NOTES_0.5.md 完整梳理本次发布的破坏性变更、弃用项、行为变化、新增能力与升级路径，并结合仓库源码（src/ogx_api/与src/ogx/）佐证各项变更的落地实现，帮助开发者在升级前完成代码与配置迁移评估。

适用版本：OGX 0.5（2026 年 2 月发布）。文中所有配置示例、命令与源码路径均以当前仓库内容为准。

---

一、升级前必读：Breaking Changes 全景图

0.5 将破坏性变更划分为三个等级，升级前需逐一对照检查。

1.1 Hard Breaking Changes（升级前必须处理）

变更	迁移方式	PR
Post-Training API 端点重构	URL 由/post-training/job/status?job_uuid=X改为/post-training/jobs/{job_uuid}/status	#4606
Embeddings API 拒绝显式null	请求中移除dimensions: null与user: null（改为省略字段）	#4644
Safety API Provider 接口变更	Provider 方法签名改为接收RunShieldRequest对象	#4643
Meta-Reference GPU Provider 移除	切换到remote::vllm或remote::ollama	#4828
基于 Scope 的端点鉴权移除	迁移到新的 YAML 端点鉴权方案	#4734

1.2 Deprecated（带迁移期，下个主版本前处理）

变更	迁移方式	PR
image_name→distro_name	配置文件中的image_name:替换为distro_name:	#4396
Eval API 调用约定	改用RunEvalRequest对象而非关键字参数	#4425
vLLMtls_verify字段	迁移到 provider 配置中的network.tls.verify	#4748

1.3 Behavior Changes（无需改代码，但需知晓）

变更	说明	PR
finish_reason值改为 OpenAI 规范	检查代码是否处理stop、length、tool_calls、content_filter	#4679
Vertex AI 默认区域改为 "global"	如依赖原区域默认值，需显式配置region	#4674
Usage token 详情字段始终存在	纯增量变化，消费者向后兼容	#4690

注意：本节表格中的 PR 编号为上游项目追踪编号，此处仅保留编号以便对照 CHANGELOG 检索，文中不列出外部链接。

---

二、Hard Breaking Changes 详解与迁移指南

2.1 Post-Training API 端点重构（#4606）

Post-Training 任务端点从查询参数迁移到路径参数，遵循 REST 最佳实践：

变更前	变更后
POST /post-training/job/cancel?job_uuid=X	POST /post-training/jobs/{job_uuid}/cancel
GET /post-training/job/status?job_uuid=X	GET /post-training/jobs/{job_uuid}/status
GET /post-training/job/artifacts?job_uuid=X	GET /post-training/jobs/{job_uuid}/artifacts

迁移方式：将所有调用 URL 中的job_uuid从查询参数改为路径参数。

2.2 Embeddings API 的 OpenAI 一致性收紧（#4644）

为达到完整 OpenAI API 一致性，/embeddings端点发生两处变化：

• dimensions与user字段拒绝显式null：此前dimensions: null被接受，现在会直接返回校验错误。
• encoding_format变为枚举：仅允许"float"或"base64"。

变更前（可接受）：

request = {"model": "test", "input": "hello", "dimensions": None}

变更后（触发 ValidationError）：

# 必须整体省略该字段，而不是置为 null request = {"model": "test", "input": "hello"}

从实现看，OGX 的 API 层基于 Pydantic 模型做请求校验（见 src/ogx_api/inference/models.py），字段约束的收紧会直接反映为 422 校验错误，客户端需要改用“省略字段”而非“显式 null”的写法。

2.3 Safety API Provider 接口变更（#4643）

Safety API 已迁移到 FastAPI routers，Provider 现在接收请求对象而非离散参数：

变更前：

async def run_shield( self, shield_id: str, messages: list, params: dict ) -> RunShieldResponse: ...

变更后：

async def run_shield(self, request: RunShieldRequest) -> RunShieldResponse: ...

同时，RunShieldRequest中未被使用的params字段已被移除。自定义 Safety Provider 实现者必须在升级时同步调整方法签名。

2.4 Meta-Reference GPU Provider 移除（#4828）

inline::meta-reference推理 Provider 的内联 GPU 实现已从代码库移除。从当前仓库的 remote provider 目录看，官方维护的推理 Provider 已覆盖vllm、ollama、openai、together、groq、mistral、deepseek、bedrock、vertexai、nvidia、sambanova、watsonx、gemini、anthropic、azure等（见 src/ogx/providers/remote/inference/），建议按如下方式迁移：

# 变更前 provider_type: inline::meta-reference # 变更后（二选一） provider_type: remote::vllm provider_type: remote::ollama

2.5 Scope-Based 端点鉴权移除（#4734）

旧的自定义端点required_scope鉴权特性已被移除，取而代之的是基于 YAML 配置的新端点鉴权方案（#4448）：

server: auth: endpoint_policy: - path: "/v1/inference/*" conditions: - role: inference-user

关于新鉴权机制的实现细节，见下文“Endpoint Authorization with YAML Config”一节。

---

三、Deprecated 项：带迁移期的兼容层

以下变更保留向后兼容，旧行为仍可工作但会输出弃用警告，请在下一个主版本前完成迁移。

3.1image_name更名为distro_name（#4396）

StackConfig中的image_name字段更名为distro_name，以更准确地反映其语义：

# 变更前 version: 2 image_name: my-stack # 变更后 version: 2 distro_name: my-stack

状态：旧的image_name仍可工作，会自动迁移并输出弃用警告。

3.2 Eval API 改用请求对象（#4425、#4683）

Eval API 现在优先使用请求对象，旧的按关键字参数调用方式被弃用但受支持：

新风格（推荐）：

await eval.run_eval(RunEvalRequest(benchmark_id="...", benchmark_config=...))

旧风格（弃用）：

await eval.run_eval( benchmark_id="...", benchmark_config=... ) # 输出 DeprecationWarning

状态：旧调用约定仍可工作但输出DeprecationWarning。#4683 已加入向后兼容层。

3.3 vLLMtls_verify配置弃用（#4748）

tls_verify字段被新的统一网络配置network.tls.verify取代：

# 变更前 providers: inference: - provider_type: remote::vllm config: url: https://vllm-server tls_verify: /path/to/ca.crt # 变更后 providers: inference: - provider_type: remote::vllm config: url: https://vllm-server network: tls: verify: /path/to/ca.crt

状态：旧tls_verify会自动迁移并输出弃用警告。

---

四、Behavior Changes：默认值与响应格式

4.1finish_reason对齐 OpenAI 规范（#4679）

推理响应的finish_reason字段现在符合 OpenAI 规范。如果代码显式检查特定值，请确认覆盖以下标准取值：stop、length、tool_calls、content_filter、function_call。

4.2 Vertex AI 默认区域变更（#4674）

Vertex AI Provider 现在默认使用 "global" OpenAI API 端点，而非特定的 GCP 区域。若依赖原默认区域，需要在 Provider 配置中显式指定region。

4.3 Usage Token 详情始终返回（#4690）

Usage对象中的input_tokens_details与output_tokens_details字段由可选变为始终返回，对消费者完全向后兼容，无需改动代码。

---

五、新特性：连接器、网络配置与鉴权

5.1 Connectors API：MCP 服务器管理（#4263、#4402、#4760）

新增用于管理 MCP（Model Context Protocol）服务器连接的 API，通过静态配置声明连接器：

connectors: - connector_id: kubernetes url: "http://localhost:8080/mcp" connector_type: mcp

API 端点：

• GET /v1alpha/connectors— 列出所有连接器
• GET /v1alpha/connectors/{connector_id}— 获取连接器详情
• GET /v1alpha/connectors/{connector_id}/tools/{tool_name}— 获取工具信息

源码佐证：连接器协议定义位于 src/ogx_api/connectors/api.py，包含get_connector、list_connectors、list_connector_tools、get_connector_tool四个操作；数据模型定义在 src/ogx_api/connectors/models.py，其中ConnectorType枚举目前仅有MCP一种类型，Connector模型除connector_id、url外还支持可选的server_label、server_name、server_description、server_version字段，用于描述已注册 MCP 服务器的元信息。连接器最终暴露的工具统一以ToolDef描述（复用 src/ogx_api/tools/ 中的工具定义），保证了与 Tool Runtime 体系的打通。

5.2 Comprehensive Network Configuration：统一网络配置（#4748）

所有远程推理 Provider 现在支持统一的网络配置，涵盖 TLS（含 mTLS）、代理服务器、超时与自定义请求头：

providers: inference: - provider_type: remote::openai config: network: tls: verify: true ca_cert: /path/to/ca.crt client_cert: /path/to/client.crt client_key: /path/to/client.key proxy: url: http://proxy:8080 timeout: connect: 10.0 read: 60.0 headers: X-Custom-Header: value

配置要点：

• tls.verify可接受布尔值（true/false）或 CA 证书路径；
• tls.ca_cert、tls.client_cert、tls.client_key组合使用即开启 mTLS 双向认证；
• proxy.url为出站代理地址；
• timeout.connect与timeout.read分别控制连接建立与读取阶段的超时（秒）；
• headers为任意自定义请求头键值对，适用于网关鉴权等场景。

该配置由远程 HTTP 客户端基础设施统一解析执行（相关实现在 src/ogx/providers/utils/inference/http_client.py），所有 remote inference Provider 共用同一套网络栈，因此一处配置、全局生效。

5.3 Endpoint Authorization with YAML Config（#4448）

提供基础设施级的 API 端点访问控制，配置方式如下：

server: auth: endpoint_policy: - path: "/v1/files*" conditions: - role: admin - path: "/v1/health" allow: true

源码佐证：OGX 的访问控制核心实现在 src/ogx/core/access_control/access_control.py。策略评估入口is_action_allowed支持permit/forbid规则、when/unless条件，以及通配符（resource::*）与regex:前缀的资源匹配（见matches_resource）；规则条件解析位于 conditions.py。当未配置任何策略时，default_policy()会回退到旧的“属性匹配 + owner 判定”逻辑以保证向后兼容——这正是从旧 Scope 鉴权迁移到新 YAML 鉴权时行为平滑过渡的底层机制。

---

六、其他新特性与能力增强

6.1 Rerankers 支持：混合检索重排（#4456）

向量库现在支持为混合检索（hybrid search）配置重排器：

results = await client.vector_stores.search( vector_store_id="vs_123", query="search query", search_type="hybrid", reranker_type="reciprocal_rank_fusion", reranker_params={"k": 60}, )

reciprocal_rank_fusion（RRF，倒数排名融合）是当前内置的重排策略，reranker_params中的k控制融合常数。该能力在多个向量库 Provider 中统一落地，包括 faiss、sqlite_vec、chroma、milvus、qdrant、weaviate、elasticsearch、pgvector、oci26ai、neo4j、infinispan 等实现（见 src/ogx/providers/utils/vector_io/vector_utils.py 及各 Provider 目录）。

6.2 Response API 增强

0.5 为 Responses API 补充了四个参数：

• reasoning.effort（#4633）：控制推理 token 使用量

  response = client.responses.create( model="openai/gpt-5", reasoning={"effort": "high"}, input=[{"role": "user", "content": "Complex problem..."}], )

• max_output_tokens（#4592）：限制响应长度

• parallel_tool_calls（#4608）：启用并行工具执行

• safety_identifier（#4793）：自定义安全监控追踪标识

这些字段在 src/ogx_api/responses/models.py 与 src/ogx_api/responses/fastapi_routes.py 中均有对应定义与路由接入。

6.3 新 Provider：Elasticsearch 与 OCI 26ai

• Elasticsearch Vector IO（#4007）：以 Elasticsearch 作为向量库后端（实现在 src/ogx/providers/remote/vector_io/elasticsearch/elasticsearch.py）；
• OCI 26ai Vector Support（#4411）：Oracle Cloud Infrastructure 26ai 作为向量库（实现在 src/ogx/providers/remote/vector_io/oci/oci26ai.py）。

6.4 PGVector 能力升级

PGVector 相关改进集中在索引策略与数据校验维度：

• HNSW 索引（#4696）：提升向量检索性能；
• IVFFlat 索引（#4772）：替代性索引策略；
• 可配置距离度量（#4714）：支持cosine、euclidean、inner_product；
• Embedding 维度校验（#4732）；
• 向量扩展自动创建（#4660）：免去手动执行CREATE EXTENSION vector。

6.5 Library Client 关闭机制（#4642）

OGXAsLibraryClient与AsyncOGXAsLibraryClient新增关闭功能，支持异步上下文管理器自动清理：

async with AsyncOGXAsLibraryClient(config_path) as client: # 使用 client ... # 退出时自动清理

6.6 Safety API：全 Provider 支持run_moderation（#4662）

OpenAI 兼容的 moderation API 支持扩展至 NVIDIA、Bedrock、SambaNova、PromptGuard 等多个 Provider。

6.7 ARM64 支持（#4474）

新增基于 UBI 的 ARM64 starter 容器镜像，支持 ARM64 架构部署。

---

七、API 全面迁移到 FastAPI Routers

0.5 将全部 API 从旧的@webmethod装饰器模式迁移到 FastAPI routers，涉及 13 个 API 域：

API	PR
Inference API	#4755
Agents/Responses API	#4376
Safety API	#4643
Eval API	#4425
Vector IO API	#4595
Conversations API	#4342
Models API	#4407
Shields API	#4412
DatasetIO API	#4400
Prompts API	#4649
Scoring API	#4521
Scoring Functions API	#4599
Post-Training API	#4496
Connectors API	#4402

收益：更好的 OpenAPI 文档自动生成、更强的请求校验与一致的错误处理。仓库中每个 API 域现在都遵循统一的api.py（协议/接口定义）+models.py（Pydantic 模型）+fastapi_routes.py（FastAPI 路由）三段式结构，例如 src/ogx_api/inference/ 与 src/ogx_api/connectors/ 均按此组织，便于新增 API 时保持架构一致。

---

八、向后兼容改进与 Bug 修复

8.1 旧数据格式兼容

多个向量库 Provider 已更新以处理旧版数据格式：

• FAISS（#4463）：处理旧版EmbeddedChunk格式；
• PGVector（#4506）：处理旧 chunk 格式；
• Qdrant（#4495）：处理旧 chunk 格式；
• Milvus（#4484）：处理旧 chunk 格式；
• SQLite-vec、Chroma、Weaviate（#4502）：处理旧 chunk 格式。

8.2 关键 Bug 修复清单

• MCP 会话清理改用上下文管理器，修复 CPU 飙升问题（#4758）；
• 修复并发加载 SentenceTransformer 的竞态条件（#4636）；
• 修复推理内容字段与 Ollama、vLLM 的兼容性（#4715）；
• 文件搜索结果现包含文档属性/元数据（#4680）；
• 修复带 OpenAI 元数据的向量库从配置注册问题（#4616）；
• 流式响应期间启用会话轮询（#4738）；
• 修复 GitHub Actions 工作流中的安全漏洞（#4752）。

---

九、0.5 升级指南

9.1 升级前：处理 Hard Breaking Changes

按以下清单逐项排查：

1. 检索 Post-Training API 调用并更新路径：

grep -r "post-training/job" .

所有匹配项更新为新格式：/post-training/jobs/{job_uuid}/...

2. 检索 Embeddings 请求中的 null 值：

grep -rE '"(dimensions|user)":\s*null' .

改为整体省略这些字段。

3. 迁移inline::meta-referenceProvider：

# 变更前 provider_type: inline::meta-reference # 变更后（二选一） provider_type: remote::vllm provider_type: remote::ollama

4. 更新自定义 Safety Provider 方法签名：

# 变更前 async def run_shield( self, shield_id: str, messages: list, params: dict ) -> RunShieldResponse: ... # 变更后 async def run_shield(self, request: RunShieldRequest) -> RunShieldResponse: ...

5. 迁移required_scope端点鉴权到 YAML 配置：

server: auth: endpoint_policy: - path: "/v1/inference/*" conditions: - role: inference-user

6. 重新生成客户端 SDK：若使用基于 OpenAPI spec 生成的客户端，需重新生成以匹配新路由与模型。

9.2 升级后：处理 Deprecations

在下一个主版本前处理以下弃用项：

1. 更新配置文件：将image_name替换为distro_name；
2. 更新 vLLM TLS 配置：将tls_verify迁移到network.tls.verify；
3. 更新 Eval API 调用：使用RunEvalRequest对象替代关键字参数。

---

十、配套文档与后续参考

0.5 同时更新了系列配套文档：

• 快速开始指南更新（#4435）；
• 从 Agents API 迁移到 Responses API 的迁移指南（#4375）；
• 集成测试贡献指南（#4460）；
• Provider 贡献指南（#4478）；
• 发布流程文档（#4470）。

需要深入了解本仓库结构与架构，可继续阅读仓库根目录的 README.md、ARCHITECTURE.md 与 AGENTS.md；完整的 Responses API 使用示例可参考 getting_started_ogx_api.ipynb 与 docs/docs/getting_started/quickstart.mdx。历史版本演进可对照 RELEASE_NOTES_1.0.md 与 RELEASE_NOTES_0.7.md。

---

小结：OGX 0.5 是一次“以 API 规范与架构健康度为优先”的版本——FastAPI 路由全面接管、OpenAI 一致性持续收紧、连接器与统一网络配置打开了更广阔的部署形态。对升级者而言，先完成本文第九节的升级前检查清单，再处理弃用项，即可平稳过渡到 0.5 体系。

【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx