企业官网建设流程全解析

OGX 版本发布说明导读：从 0.5 到 1.0 的破坏性变更清单与发布工程实践

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

OGX（Open GenAI Stack）在仓库根目录维护着一份汇总式发布说明 RELEASE_NOTES.md，它为每个版本提供“摘要 + 亮点 + 破坏性变更速查表”，并通过相对链接指向docs/releases/下包含完整迁移指南的详细发布说明。本文以该文件为主体，完整梳理 0.5.0 与 0.7.0 两个版本的发布内容、破坏性变更及升级步骤，结合 1.0 稳定版的详细发布说明、发布说明的自动化生成流程（docs/releases/GENERATE.md）以及仓库源码中的实现证据，帮助你在升级 OGX 之前快速定位所有需要改动之处。

发布说明文档体系：汇总层与详细层

OGX 的发布说明采用两级结构：

1. 汇总层：RELEASE_NOTES.md（仓库根目录）。文件头部有一条 HTML 注释<!-- New releases go here, at the top. -->，作为新版本摘要的插入锚点；每个版本条目以## 版本号 - 发布日期的形式出现，包含一段概述、Highlights 列表和一张破坏性变更表（Change / Type / PR 三列），并在结尾链接到详细发布说明。
2. 详细层：docs/releases/目录下的版本专属文档，当前仓库中包括 RELEASE_NOTES_0.5.md、RELEASE_NOTES_0.7.md 和 RELEASE_NOTES_1.0.md。详细文档在汇总表之外，为每条破坏性变更单独展开Impact（影响面）/ Before-After 示例 / Migration（迁移步骤），并给出含grep命令的“升级前/升级后”操作清单。

从仓库当前状态看，pyproject.toml 中fallback_version = "1.3.1.dev0"，说明当前代码处于 1.x 系列之后；而 src/ogx_api/version.py 中定义了三个 API 级别常量OGX_API_V1 = "v1"、OGX_API_V1BETA = "v1beta"、OGX_API_V1ALPHA = "v1alpha"，这正是发布说明中反复出现的/v1、/v1beta、/v1alpha路由前缀的来源——API 分级（leveling）是贯穿 0.5 → 0.7 → 1.0 各次变更的组织框架。

0.7.0 版本：完成 OpenAI API 对齐的关键版本（2026-04-01）

汇总层对该版本的定位是：一个聚焦于完成向 OpenAI API 兼容性（conformance）过渡、引入全面可观测性指标、并进行大规模 API 清理的主要版本。它移除了 fine-tuning API、完成了 FastAPI 路由迁移、移除了遗留 provider（TGI、HuggingFace）、重命名了核心概念，并通过 structlog 引入结构化日志。

0.7.0 Highlights

• Agents API 更名为 Responses API，与 OpenAI 命名保持一致（PR #5195）
• Responses API 支持推理输出（Reasoning output）（PR #5206）
• 全面的可观测性指标，覆盖 API、推理与向量 IO 三个层面（PR #5201、#5320、#5096）
• 基于 structlog 的结构化日志，输出键值对（PR #5215）
• RAG 内联神经重排（Inline neural rerank），无需外部服务（PR #4877）
• 内联 Docling provider，面向结构感知的 PDF 解析（PR #5049）
• Infinispan vector-io provider，用于分布式向量存储（PR #4839）
• Connector API 晋升至 v1beta（PR #5129）
• FastAPI 路由迁移完成，@webmethod装饰器移除（PR #5248）
• 性能优化：torch、numpy、faiss、braintrust 延迟加载以降低启动内存（PR #5116、#5118、#5078）

这些亮点在当前代码库中均有对应实现痕迹：

• 结构化日志：src/ogx/log.py 中可见import structlog以及structlog.contextvars.merge_contextvars、structlog.processors.TimeStamper(fmt="iso")、structlog.processors.StackInfoRenderer()等处理器配置（约 L339-L350），印证了日志输出已迁移到键值对格式；
• 可观测性指标：src/ogx/telemetry/ 目录下存在inference_metrics.py、vector_io_metrics.py、tool_runtime_metrics.py等模块，与“API / inference / vector IO 指标”三项能力一一对应；
• Responses API 更名：src/ogx_api/responses/ 目录提供api.py、fastapi_routes.py、models.py，体现“所有 API 统一走 FastAPI 路由”的架构（@webmethod已无从查找）。

0.7.0 破坏性变更（Breaking Changes）

以下为汇总层的完整变更表（Hard = 升级前必须处理；Behavior = 无需改代码但需知悉）：

详细层（RELEASE_NOTES_0.7.md）在此基础上补充了逐项迁移细节，其中几个值得展开：

Provider 命名重映射（配置侧最常见的改动）：

grep -r "meta-reference" your-config-directory/ grep -r "rag-runtime" your-config-directory/ grep -r "starter-gpu" your-config-directory/

映射关系为：inline::meta-reference→inline::builtin；inline::rag-runtime→inline::file-search；toolgroup_id中的builtin::rag→builtin::file-search；starter-gpu→starter。

工具与端点重命名：

grep -r "knowledge_search" your-project/ # 全部替换为 file_search grep -r "/agents" your-project/ # /agents/* 端点替换为 /responses/* grep -r "tool_groups\|register_tool" your-project/ grep -r "remote::tgi\|remote::huggingface" your-config-directory/ grep -r "register_model\|unregister_model" your-project/

被移除的 TGI / HuggingFace 推理 provider 可切换到remote::vllm、remote::ollama等其他受支持的推理 provider；tool_groups改为由 provider spec 自动注册，不再需要手工注册调用。

行为变更（无需改代码）：sentence_transformers出于安全考虑将trust_remote_code默认置为False，若使用需要远程代码执行的自定义模型，须在 provider 配置中显式设置trust_remote_code: true；日志格式改为 structlog 结构化键值对，依赖旧格式的日志解析工具需要更新。

此外，0.7 的新特性还包括：Responses API 的推理输出支持、后台响应取消端点（PR #5268）、stream_options参数支持（PR #4815）、PGVector 元数据过滤（PR #5111）、可配置的 asyncpg 连接池（PR #5160）、以及 Infinispan 向量存储 provider 等，详见 RELEASE_NOTES_0.7.md 的 New Features 部分。

0.5.0 版本：API 一致性与 FastAPI 路由迁移（2026-02-05）

汇总层对 0.5 的概括是：显著提升 API 一致性、OpenAI 兼容性与 provider 能力，并将所有 API 重构为使用 FastAPI 路由的架构级版本。

0.5.0 Highlights

• Connectors API：管理 MCP server 连接（PR #4263）
• 统一网络配置：所有远程 provider 支持 TLS/mTLS、代理与超时（PR #4748）
• 基于 YAML 访问控制的端点授权（PR #4448）
• 向量存储的 Reranker，支持混合检索（PR #4456）
• Response API 增强：reasoning.effort、max_output_tokens、parallel_tool_calls
• 新 provider：Elasticsearch 与 OCI 26ai 向量存储
• PGVector 改进：HNSW/IVFFlat 索引、可配置距离度量
• FastAPI 路由迁移：覆盖所有 API，改善 OpenAPI 文档与校验
• ARM64 容器镜像支持（PR #4474）

0.5.0 破坏性变更

汇总层速查表如下：

详细层（RELEASE_NOTES_0.5.md）补充了 Before/After 对照，例如 Post-Training 端点从查询参数改为 REST 风格路径参数：

Deprecated 项的配置迁移示例：配置文件中image_name:替换为distro_name:；vLLM 的tls_verify字段迁移到network.tls.verify（与 0.5 引入的统一网络配置合并）。另有三条行为变更需注意：finish_reason取值变为 OpenAI 规范（stop/length/tool_calls/content_filter）、Vertex AI 默认 region 变为global、usage 中的 token 明细始终存在（加法性变更，无需处理）。

1.0 稳定版：版本演进的落点

RELEASE_NOTES_1.0.md（2026 年 5 月发布）虽然不在根目录汇总表中，但它是理解 0.5 → 0.7 变更意图的落点：1.0 是 OGX 的首个 major-stable 版本，/v1HTTP API 面被纳入稳定性契约（详见其引用的 API 分级文档docs/docs/concepts/apis/api_leveling.mdx）——1.x 系列内不改变/v1数据类型与磁盘存储 schema；未稳定 API 继续留在/v1alpha与/v1beta下（与 src/ogx_api/version.py 中的三个常量呼应）。

1.0 的核心主题包括：面向 MaaS 部署的多租户核心（跨存储、向量存储、prompts、conversations 的租户隔离）、将授权作为一等存储关注点（所有受访问控制 API 经由AuthorizedSqlStore）、管理面/数据面分离（tools、connectors迁出/v1）、移除 Safety API 并改用 OpenAI 兼容的/v1/moderations端点、ogx_api包拆分为ogx_api.types与ogx_api.provider两个命名空间、以及 Gateway-first 服务器架构（认证、限流、租户解析统一收敛在网关层）。其硬性破坏性变更共 10 条（Safety API 移除、/v1/tools→/v1/admin/tools、/v1/connectors→/v1alpha/admin/connectors、多租户默认强制、logprobs由bool改为int、ogx stack rm命令移除等），升级前需先备份存储，因为 connectors/batches 的 KVStore 迁移是单向的。

发布说明的生成流程：可复制的工程实践

docs/releases/GENERATE.md 描述了一条完整的发布说明生成流水线：将版本区间（OLD_VERSION/NEW_VERSION）作为前缀与提示词文件一起通过管道交给 Claude Code 执行，最终产出三件制品——docs/releases/RELEASE_NOTES_{VERSION}.md详细文档、追加到根目录RELEASE_NOTES.md顶部的摘要段落、以及对应的 Pull Request。

其流程设计本身即是可借鉴的发布工程实践：

1. 变更分析：定位两个版本间的 git tag，取全部提交；对 conventional commits 中带!的提交检查实际 diff，同时人工审查未标记提交中是否存在不兼容变更（API schema 变化、默认值变化、功能移除、配置字段重命名、方法签名变化）。
2. 破坏性变更三分法：
   • Hard Breaking Changes——不改动代码/配置就会失败，升级前必须处理；
   • Deprecated——带有后向兼容层与告警，应迁移；
   • Behavior Changes——默认值或响应格式变化，代码无需改动但需知悉。 根目录汇总表中的Type列（Hard / Deprecated / Behavior）即源于此分类。
3. 详细文档结构：固定为标题 → 发布日期 → 一段式概述 → 带汇总表的 Breaking Changes（每项含影响面、Before/After 代码示例、迁移步骤）→ 按主题分组的 New Features → 新 Provider → API/架构变更 → Bug Fixes → 升级指南（“升级前”逐条给出grep命令定位受影响代码，“升级后”处理废弃项）。
4. 汇总文档更新规则：新摘要插入在 HTML 注释锚点下方，采用 ISO 日期，Highlights 精选 5–10 条，破坏性变更表仅列类型不含迁移细节，最新版本始终置顶。
5. 提交规范：分支名docs/release-notes-{NEW_VERSION}，提交信息docs: add release notes for version {NEW_VERSION}。

实操建议：如何使用这份发布说明

• 升级前先读汇总表：以 RELEASE_NOTES.md 中对应版本的 Breaking Changes 表为检查清单，逐条确认自己的代码与配置是否命中（Type=Hard的行必须在升级前处理完）。
• 命中条目再进详细文档：按表中链接进入docs/releases/RELEASE_NOTES_x.y.md对应小节，按其中的 Before/After 示例与grep命令执行替换；1.0 及 0.7 的 Upgrade Guide 小节已把升级前/后动作整理成带命令的编号清单，可直接照做。
• 关注行为变更：即使grep无命中，也要检查日志解析、finish_reason处理、trust_remote_code依赖等 Behavior 类条目。
• API 稳定性预期：若你的代码面向/v1面编写，自 1.0 起在 1.x 内可获得数据类型与存储 schema 不破坏的承诺；面向/v1alpha、/v1beta的调用则需持续跟进发布说明。

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