OGX 1.0 版本全解读多租户核心、网关优先架构与 v1 稳定性契约升级指南【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogxOGXOpen GenAI Stack1.0 是项目的首个 major-stable 版本围绕 MaaSModel-as-a-Service部署场景重构了多租户隔离、授权存储与网关架构并首次将/v1API 纳入正式稳定性契约。本文以官方 Release Notes 为骨架结合仓库源码与架构文档系统拆解 1.0 的 10 项硬破坏性变更、新特性、性能与安全改进并给出可直接执行的升级迁移清单帮助开发者在升级前完成所有必要改动。版本定位与稳定性契约Release Date: May 2026OGX 1.0 发布的核心信号是/v1HTTP API 面进入稳定期。根据docs/docs/concepts/apis/api_leveling.mdx中定义的稳定性分级体系/v1stableZ-stream补丁版本之间保持向后兼容数据类型的破坏性变更必须经过正式的批准与公告流程。/v1beta路由保持一致但参数与返回类型不作跨版本保证。/v1alpha几乎不承诺支持允许任意破坏性变更、增删路由。1.0 承诺在1.x 版本线内不破坏/v1数据类型与磁盘存储 schema尚未稳定的 API 继续驻留在/v1alpha与/v1beta。这一契约同样覆盖config.yaml等 StackConfig 数据类型1.4.2能加载的配置在1.4.3、1.5.0上必须仍能加载配置 schema 的破坏性变更同样需要 major 版本。存储层的兼容性规则见 api_leveling.mdx 数据存储兼容性进一步规定Z-stream 升级无 schema 变化Y-stream 升级仅允许加性、自动迁移的 schema 变化major 升级可能要求显式迁移脚本降级不在支持范围需要回滚的操作者应在升级前做快照。OGX 还为此建立了backward-compat.yml等 CI 工作流在每次 PR 时校验 main 分支与最新发布版本的 config 能否在 PR 分支上正常加载。1.0 的五大主题面向 MaaS 部署的多租户核心——存储、向量库、提示词、会话等资源实现一等公民的租户隔离。授权成为存储层的一等公民——所有受访问控制的 API 统一经由AuthorizedSqlStore。管理面 / 数据面拆分——tools、connectors等管理路由迁出面向用户的/v1面。移除 Safety API——由 OpenAI 兼容的 moderation 端点取代。ogx-api命名空间拆分——ogx_api.types数据类型与ogx_api.providerProvider 编写面成为各自独立的稳定面。网关优先的服务端架构——认证、限流、租户解析等边缘关注点统一收敛到网关层。破坏性变更一览升级到 1.0 前必须处理的硬破坏性变更如下表所示变更迁移方式PRSafety API 移除改用/v1/moderations用 moderation 端点替换run-shield与shields调用#5291, #5744Tools 路由迁移至/v1/admin/tools工具管理客户端改用/v1/admin/tools#5787Connectors 路由迁移至/v1alpha/admin/connectors更新连接器管理客户端#5659多租户强制默认开启提供租户凭据/请求头复核各租户数据隔离范围#5756受访问控制的 API 必须使用AuthorizedSqlStore自定义 Provider 必须从原始SqlStore迁移#5776Connectors 与 Batches 的 KVStore 迁移至AuthorizedSqlStore首次启动执行磁盘迁移先备份状态#5757/v1/models响应结构改为多 SDK 形态解析旧结构的客户端需要更新#5522ogx-api拆分为ogx_api.types与ogx_api.provider更新 Provider 代码与下游消费者的导入路径#5740Completions 的logprobs类型由bool改为int将logprobsTrue/False改为整数#5343移除ogx stack rmCLI 命令改用发行版distribution专属的拆除方式#5735硬破坏性变更详解1. Safety API 移除由 Moderation 端点取代#5291, #5744影响面所有使用/v1/safety/run-shield与/v1/shields列表/查询端点的用户。独立的 Safety API 已整体移除内容审核统一由 OpenAI 兼容的/v1/moderations端点提供。Shield 注册与列表端点一并删除审核模型改为通过 Provider 配置来指定。迁移将run-shield调用替换为/v1/moderations。从源码看moderation 能力已融入 builtin Responses Provider 的实现中相关逻辑位于 src/ogx/providers/inline/responses/builtin/responses/openai_responses.py 与 src/ogx/providers/inline/responses/builtin/config.py审核模型的配置入口即在此 Provider 配置中完成。2. Tools 路由迁移至/v1/admin/tools#5787影响面调用/v1/tools进行工具管理的客户端。工具管理端点已迁至管理路径/v1/admin/tools将控制面与用户面 API 分离。路由注册可在 src/ogx_api/admin/fastapi_routes.py 中看到/admin/tools与/admin/connectors、/admin/providers、/admin/health、/admin/version等管理路由同属管理面。迁移工具管理客户端改用新路径最终用户在 Responses/Chat Completions 中调用工具的代码不受影响。3. Connectors 路由迁移至/v1alpha/admin/connectors#5659影响面管理 MCP 连接器的客户端。连接器管理迁移到/v1alpha/admin/connectors既体现其管理面定位也反映其处于 pre-stable 的 API 等级参考 api_leveling.mdx 中 v1alpha 的语义。迁移更新连接器管理客户端到新路径。4. 面向 MaaS 部署的多租户核心#5756影响面所有未显式配置租户的部署。OGX 1.0 内置了适合 MaaS 部署的一等公民多租户隔离租户上下文贯穿存储、向量库、会话与提示词。随版本一同发布的有向量库元数据租户隔离#5782与提示词租户隔离测试#5758。在源码层面租户模型由 src/ogx/core/datatypes.py 中的TenancyMode与TenancyConfig定义class TenancyMode(StrEnum): DISABLED disabled SINGLE single MULTI multi class TenancyConfig(BaseModel): mode: TenancyMode Field(defaultTenancyMode.DISABLED, descriptionTenancy mode: disabled, single, or multi)其中SINGLE模式要求显式配置default_tenant_id否则配置校验不通过。三种模式的含义依据 ADR-0001 网关优先架构disabled不做租户强制兼容既有单租户与纯 ABAC 部署。single所有资源归属一个配置的租户适合单租户生产或开发模式无需网关。multi完整租户隔离租户作用域路由上每个请求都必须解析出tenant_id。迁移单租户部署必须显式选择默认租户或配置租户凭据检查任何直接操作存储的自定义 Provider——它们必须改用AuthorizedSqlStore。5. 受访问控制的 API 必须使用AuthorizedSqlStore#5776影响面使用原始SqlStore存储租户作用域数据的自定义 Provider 作者。需要访问控制的 API 现在强制使用AuthorizedSqlStore它把租户身份集成到每一次查询中。从 src/ogx/core/storage/sqlstore/authorized_sqlstore.py 的实现可以看到其核心机制包装基础SqlStore叠加访问控制策略AccessRule列表与tenancy_mode、default_tenant_id。写入时通过_enhance_item_with_access_control()剥除客户端提交的owner_principal、access_attributes、tenant_id改由当前认证用户填充——即绝不信任客户端提供的访问控制字段。查询时先按tenant_id硬分区再应用 ABAC 策略owner 或属性匹配并对默认策略做了 SQL 层过滤优化SQL_OPTIMIZED_POLICY。进程级租户配置由set_default_tenancy_config()在 stack 初始化时设置authorized_sqlstore()是获取受授权 SQL 存储的唯一受支持方式。迁移自定义 Provider 对租户作用域表应改用AuthorizedSqlStore构造而非直接使用SqlStore。6. Connectors 与 Batches KVStore 迁移至 AuthorizedSqlStore#5757影响面存储了连接器或批次状态的存量部署。1.0 首次启动时连接器与批次状态会从旧的 KVStore 布局迁移到AuthorizedSqlStore支撑的表。这与 ADR-0001 中Prompts、Connectors、Batches 完成 KV 到 SQL 迁移的阶段规划一致。迁移升级前先备份存储。该迁移为单向不支持降级回滚。7./v1/models响应结构改为多 SDK 形态#5522影响面解析旧版/v1/models响应的客户端。/v1/models现在按各 SDK 约定OpenAI、Anthropic 等返回对应形态而不是单一 OGX 专属结构。迁移更新解析模型元数据的客户端到新结构完整 schema 见 API 参考。8.ogx-api命名空间拆分为types与provider#5740影响面直接from ogx_api import X的代码。ogx_api被拆分为两个稳定性规则各异的独立面依据 api_leveling.mdx 公开数据类型稳定性ogx_api.types—— 线上传输所用的 Pydantic 数据类型遵循/v1稳定性契约按被引用路由的最高等级逐类型定级一旦成为v1便不可降级。ogx_api.provider—— Provider 作者使用的基类与协议整体按v1稳定面对待跨 Y-stream 保持源码兼容新增能力必须是纯加性变更。ogx_api.types的v1兼容规则包括只允许添加带安全默认值的可选字段、放宽联合类型、添加新模型类而字段重命名、类型非加性变更、可选变必填、从Literal/Enum移除成员等均视为破坏性变更。Provider SDK 面则要求向已有协议类添加抽象方法必须有默认实现任何删除、重命名、签名收紧都要求ogx-api升 major。迁移更新导入路径。1.0 中旧的顶层导入仍以过渡 shim 形式保留但将在 2.0 中移除——新代码请直接使用显式命名空间路径。9. Completions 的logprobs类型bool→int#5343影响面向/v1/completions传logprobsTrue/False的客户端。logprobs参数现在接收整数返回的 top logprobs 数量与 OpenAI Completions API 对齐。迁移将True替换为整数如1或5将False替换为省略该字段。10. 移除ogx stack rmCLI 命令#5735影响面运行ogx stack rm的用户。该命令可发现性差且极少使用因此被移除。迁移使用发行版专属的拆除方式容器停止、uv虚拟环境清理等。OGX 的 distribution 模型见 src/ogx/distributions/README.md提供starter、oci、watsonx、nvidia、ci-tests等发行版各发行版的启动/拆除脚本独立管理其生命周期。新特性多租户与授权面向 MaaS 部署的多租户核心#5756向量库元数据租户隔离#5782AuthorizedSqlStore在受访问控制 API 中的强制落地#5776Connectors 与 Batches 迁移至AuthorizedSqlStore#5757提示词租户隔离 CI 工作流#5758GitHub 组织成员资格拉取用于 RBAC 属性映射#5711网关优先的服务端架构#5750认证、限流、租户解析等边缘关注点从分散的 handler 中收敛到网关层。依据 ADR-0001 的职责划分网关负责TLS 终止、边缘限流与 IP 白名单、CORS、熔断与负载均衡、跨 OGX 实例的请求路由、生产环境认证校验 token 并向 OGX 注入tenant_id/user_id/claims 等身份头且必须剥离客户端伪造的身份头。OGX 保留身份与租户提取、基于 ABAC 的资源授权、存储资源的租户隔离、语义级请求指标、请求上下文传播。ADR 特别论证了资源授权不能迁移到网关POST /v1/responses请求引用的向量库、会话、文件、模型归属校验都必须查询 OGX 数据库网关无法独立完成。同时它明确了几条硬性部署不变量使用upstream_header认证时 OGX 不得被客户端直连、网关必须剥离客户端身份头、租户上下文只能来自可信认证源。新的推理 Provider 与兼容性letsgo支持 Gemini 与 Azure#5706letsgo支持 Claude Code 兼容#5709letsgo中的inline::auto文件处理器#5704落地页新增 Claude Code、Codex、OpenCode 的 CLI 展示#5716文件处理inline::auto复合文件处理器#5673inline::markitdownProvider 接入 auto 调度器#5688会话与交互多轮会话的previous_interaction_id#5669增强 Conversations 的 OpenAI API 覆盖#5748Chat Completions 消息列表端点#5459Conversation list_items 的游标分页与has_more#5612Files增强 Files API 的 OpenAI API 覆盖#5747CLI顶层ogx run与ogx letsgo快捷命令#5689ogx-api包引入ogx_api.provider与ogx_api.types命名空间#5740数据类型稳定性与包面文档#5719性能改进PostgreSQL kvstore 引入 asyncpg 连接池#5734PostgreSQL KV Store 从 psycopg2 迁移到 asyncpg#5739Responses API 流式期间的批量化 guardrail 检查#5664显式 HTTP 超时与改进的连接池#5737安全修复通过 Ruff bandit 规则与 CodeQL 扫描实现 Python SAST#5738修复 python-multipart、protobuf、lxml 与 npm 包中的高危 CVE#5775关键与高危依赖升级#5742将 CVE 固定的传递依赖迁移到 constraint-dependencies#5707解决ogx_apiconstraint-dependencies 中的 Dependabot 告警#5778NVIDIA Provider修正 hostname 校验的 URL 解析#5777Bug 修复线程安全的OGXAsLibraryClient#5773SQLite-vec 的 WAL 模式与busy_timeout#5428Gemini 流式剥离逐 chunk usage 以防止 token 重复计数#5171Responses API输入条目检索时尊重include#5605Auth仅在认证服务故障时返回 503#5715AuthOAuth2 introspection 尊重verify_tls#5710OpenAI将max_tokens收敛到各模型上限#5696OllamaOpenAI 预处理中容忍 dict 型推理消息#5638Vertex AI多轮会话中将reasoning_content保留为 thought parts#5677NVIDIA safetyNeMoGuardrails 模型使用provider_resource_id#5726PostgreSQL 存储keys_in_range()过滤过期行#5712SQL store正确传播真实的 add-column 错误#5713KVStore全后端支持命名空间与过期过滤#5731Vector IO改进文件处理器拒绝时的错误报告#5690Starter extra补充缺失依赖#5674测试参数化用provider_type替代provider_id#5263重构、文档与 CI/CD重构服务端采用网关优先架构处理边缘关注点#5750跨代码库死代码清理#5779。文档数据类型稳定性与ogx-api包面文档#5719一致化 agentic API 层博客#5687落地页推广库模式#5761Provider 卡片 / DocCardList 重设计#5694Claude Code--model示例与路由说明澄清#5692。CI/CDrecord-integration-testsaction 引用固定到合并提交 SHA#5762打破 record-integration-tests 反馈回路#5781re-record 工作流覆盖全部 Ollama 变体#5746为免费计划限额减少 GitHub Actions runner 使用#5751PR 集成测试仅用 server 客户端#5697breaking-change 确认正则允许 conventional-commit scope#5718。升级指南升级前必做Before Upgrading以下硬破坏性变更要求在运行 1.0 之前完成更新1. 备份存储。Connectors/Batches 的 KVStore 迁移是单向的无法降级。2. 替换 Safety API 用法。grep -r /v1/safety\|run-shield\|/v1/shields your-project/切换到/v1/moderations。3. 更新管理路由客户端。grep -r /v1/tools\b your-project/ grep -r /v1/connectors\b\|/v1alpha/connectors\b your-project//v1/tools→/v1/admin/tools/v1/connectors→/v1alpha/admin/connectors4. 配置租户。单租户部署必须选择默认租户或提供租户凭据。复核涉及存储的 Provider 配置确认租户作用域数据走AuthorizedSqlStore。参考 src/ogx/core/datatypes.py 中的TenancyModedisabled保持原行为single必须设置default_tenant_idmulti强制每个请求解析租户。5. 更新 Completions 的logprobs调用者。grep -rn logprobs.*\s*\(True\|False\) your-project/将布尔值替换为整数或省略该字段。6. 更新/v1/models解析器以适配新的多 SDK 响应结构。7. 更新ogx_api导入按需改用ogx_api.types或ogx_api.provider。1.0 提供过渡 shim但 2.0 将移除。升级后核对After Upgrading自定义 Provider 作者将受访问控制表上的直接SqlStore用法迁移到AuthorizedSqlStore。复核认证/限流配置结合新的网关优先架构审视参考 ADR-0001 中网关与 OGX 的职责边界以及UpstreamHeaderAuthProvider的信任边界与身份头剥离要求。验证多租户数据隔离若为共享部署用新的向量库元数据隔离功能核对各租户数据作用域。总结OGX 1.0 是一次以生产化、多租户、稳定性为轴心的里程碑发布/v1稳定性契约让 API 与存储进入可预期的演进轨道多租户核心与AuthorizedSqlStore让 MaaS 部署获得一等公民的租户隔离网关优先架构重新划定了边缘关注点与资源授权的边界ogx_api的命名空间拆分则为 Provider 生态提供了清晰的契约面。对现有用户而言10 项硬破坏性变更大多可通过先备份、再 grep、后替换的方式平滑完成而升级后的架构将支撑更复杂、更隔离的生产场景。【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考