ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

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

OGX 版本发布说明导读:从 0.5 到 1.0 的破坏性变更清单与发布工程实践 OGX 版本发布说明导读从 0.5 到 1.0 的破坏性变更清单与发布工程实践【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogxOGXOpen GenAI Stack在仓库根目录维护着一份汇总式发布说明 RELEASE_NOTES.md它为每个版本提供“摘要 亮点 破坏性变更速查表”并通过相对链接指向docs/releases/下包含完整迁移指南的详细发布说明。本文以该文件为主体完整梳理 0.5.0 与 0.7.0 两个版本的发布内容、破坏性变更及升级步骤结合 1.0 稳定版的详细发布说明、发布说明的自动化生成流程docs/releases/GENERATE.md以及仓库源码中的实现证据帮助你在升级 OGX 之前快速定位所有需要改动之处。发布说明文档体系汇总层与详细层OGX 的发布说明采用两级结构汇总层RELEASE_NOTES.md仓库根目录。文件头部有一条 HTML 注释!-- New releases go here, at the top. --作为新版本摘要的插入锚点每个版本条目以## 版本号 - 发布日期的形式出现包含一段概述、Highlights 列表和一张破坏性变更表Change / Type / PR 三列并在结尾链接到详细发布说明。详细层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 路由迁移、移除了遗留 providerTGI、HuggingFace、重命名了核心概念并通过 structlog 引入结构化日志。0.7.0 HighlightsAgents API 更名为 Responses API与 OpenAI 命名保持一致PR #5195Responses API 支持推理输出Reasoning outputPR #5206全面的可观测性指标覆盖 API、推理与向量 IO 三个层面PR #5201、#5320、#5096基于 structlog 的结构化日志输出键值对PR #5215RAG 内联神经重排Inline neural rerank无需外部服务PR #4877内联 Docling provider面向结构感知的 PDF 解析PR #5049Infinispan vector-io provider用于分布式向量存储PR #4839Connector API 晋升至 v1betaPR #5129FastAPI 路由迁移完成webmethod装饰器移除PR #5248性能优化torch、numpy、faiss、braintrust 延迟加载以降低启动内存PR #5116、#5118、#5078这些亮点在当前代码库中均有对应实现痕迹结构化日志src/ogx/log.py 中可见import structlog以及structlog.contextvars.merge_contextvars、structlog.processors.TimeStamper(fmtiso)、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 无需改代码但需知悉变更类型PR移除 Fine-tuning APIHard#5104meta-referenceprovider 更名为builtinHard#5131knowledge_search更名为file_searchHard#5186Agents API 更名为 Responses APIHard#5195tool_groups从公共 API 中移除Hard#4997TGI 与 HuggingFace provider 移除Hard#5333register/unregister模型端点移除Hard#5341webmethod装饰器移除Hard#5248rag-runtimeprovider 更名为file-searchHard#5187移除重复的dataset_id参数Hard#4849统一/files/{file_id}GET 响应Hard#5154OpenAI API schema 转换Hard#5166starter-gpu发行版distribution移除Hard#5279sentence_transformers的trust_remote_code默认值改为FalseBehavior#4602详细层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::builtininline::rag-runtime→inline::file-searchtoolgroup_id中的builtin::rag→builtin::file-searchstarter-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等其他受支持的推理 providertool_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 HighlightsConnectors API管理 MCP server 连接PR #4263统一网络配置所有远程 provider 支持 TLS/mTLS、代理与超时PR #4748基于 YAML 访问控制的端点授权PR #4448向量存储的 Reranker支持混合检索PR #4456Response API 增强reasoning.effort、max_output_tokens、parallel_tool_calls新 providerElasticsearch 与 OCI 26ai 向量存储PGVector 改进HNSW/IVFFlat 索引、可配置距离度量FastAPI 路由迁移覆盖所有 API改善 OpenAPI 文档与校验ARM64 容器镜像支持PR #44740.5.0 破坏性变更汇总层速查表如下变更类型PRPost-Training API 端点重构改用路径参数Hard#4606Embeddings API 拒绝显式null的可选字段Hard#4644Safety API provider 接口改为请求对象Hard#4643移除 Builtin GPU 推理 providerHard#4828移除基于 Scope 的端点授权Hard#4734image_name更名为distro_nameDeprecated#4396Eval API 调用约定改用请求对象Deprecated#4425vLLM 的tls_verify迁移到network.tls.verifyDeprecated#4748详细层RELEASE_NOTES_0.5.md补充了 Before/After 对照例如 Post-Training 端点从查询参数改为 REST 风格路径参数BeforeAfterPOST /post-training/job/cancel?job_uuidXPOST /post-training/jobs/{job_uuid}/cancelGET /post-training/job/status?job_uuidXGET /post-training/jobs/{job_uuid}/statusGET /post-training/job/artifacts?job_uuidXGET /post-training/jobs/{job_uuid}/artifactsDeprecated 项的配置迁移示例配置文件中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.md2026 年 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。其流程设计本身即是可借鉴的发布工程实践变更分析定位两个版本间的 git tag取全部提交对 conventional commits 中带!的提交检查实际 diff同时人工审查未标记提交中是否存在不兼容变更API schema 变化、默认值变化、功能移除、配置字段重命名、方法签名变化。破坏性变更三分法Hard Breaking Changes——不改动代码/配置就会失败升级前必须处理Deprecated——带有后向兼容层与告警应迁移Behavior Changes——默认值或响应格式变化代码无需改动但需知悉。 根目录汇总表中的Type列Hard / Deprecated / Behavior即源于此分类。详细文档结构固定为标题 → 发布日期 → 一段式概述 → 带汇总表的 Breaking Changes每项含影响面、Before/After 代码示例、迁移步骤→ 按主题分组的 New Features → 新 Provider → API/架构变更 → Bug Fixes → 升级指南“升级前”逐条给出grep命令定位受影响代码“升级后”处理废弃项。汇总文档更新规则新摘要插入在 HTML 注释锚点下方采用 ISO 日期Highlights 精选 5–10 条破坏性变更表仅列类型不含迁移细节最新版本始终置顶。提交规范分支名docs/release-notes-{NEW_VERSION}提交信息docs: add release notes for version {NEW_VERSION}。实操建议如何使用这份发布说明升级前先读汇总表以 RELEASE_NOTES.md 中对应版本的 Breaking Changes 表为检查清单逐条确认自己的代码与配置是否命中TypeHard的行必须在升级前处理完。命中条目再进详细文档按表中链接进入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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表