OGX 架构深度解析：统一 API 协议层、Provider 解析与自动路由的完整技术内幕

OGX 架构深度解析统一 API 协议层、Provider 解析与自动路由的完整技术内幕【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogxOGXOpen GenAI Stack是一个面向 AI 能力统一暴露的服务器它以一套稳定的 API 同时提供推理inference、响应编排responses、向量存储vector IO、工具执行tool runtime、评测evaluation等能力并对底层后端完全供应商无关——同一份 API 无论背后是 Ollama、OpenAI、vLLM 还是 Fireworks 都保持一致。本文以仓库根目录的 ARCHITECTURE.md 为骨架结合 src/ogx/core、src/ogx_api 等源码实现完整拆解 OGX 的模块边界、请求流转、Provider 体系、存储与租户隔离、配置模型以及录制回放测试系统。读完本文你将掌握 OGX 的核心架构设计能够快速定位各功能模块源码、理解 run config 的每个关键字段并清楚一个 HTTP 请求是如何被路由到正确的 Provider 的。系统概览三个包的职责边界OGX 代码库被拆分为三个独立包职责划分非常清晰包路径职责ogx-apisrc/ogx_api轻量级 API 协议定义包PythonProtocol类、Pydantic 数据类型、Provider 规格定义。不含任何服务端代码不含任何 Provider 实现。第三方 Provider 只依赖这一个包ogxsrc/ogx服务端实现Provider 解析、路由routing、存储、CLI以及全部内置 Providerogx-uisrc/ogx_ui可选 Web UI聊天游乐场chat playground与管理员界面基于 Next.js 构建这种拆分的直接收益是依赖隔离第三方 Provider 作者只需安装ogx-api即可编写自己的 Provider不需要拉入整套服务端代码而ogx作为宿主按需加载 Provider。在 src/ogx/core/stack.py 中OGX是一个复合协议类它一次性继承Providers、Inference、Responses、Batches、VectorIO、Models、Inspect、Files、Prompts、Conversations、Connectors等全部 API 接口把整个服务端组合成一个实现了所有协议的完整对象——这正是一套 API 覆盖所有能力在类型层面的落地。请求流转从 HTTP 请求到 Provider 的完整链路中间件链与路由分发OGX 服务端构建在 FastAPI 之上。请求进入后依次经过多层中间件再进入路由分发。整体流转如下Client (ogx-client SDK or raw HTTP) | v FastAPI Server (src/ogx/core/server/server.py) | |-- AuthenticationMiddleware (token validation, user tenant_id extraction) |-- TenancyMiddleware (enforces tenancy mode: disabled/single/multi) |-- RouteAuthorizationMiddleware (route-level access policies) | v Route Dispatch | |-- FastAPI Router routes (auto-discovered via fastapi_router_registry.py) | v Router (src/ogx/core/routers/) | |-- Looks up the resource (model, vector store, tool group, etc.) in the RoutingTable |-- Resolves which provider handles this resource |-- Enforces access control policies | v Provider Implementation | |-- Inline provider (runs in-process, e.g. meta-reference, sqlite-vec) |-- Remote provider (calls external service, e.g. ollama, openai, fireworks) | v External Service or Local Computation从源码看src/ogx/core/server/server.py 明确导入了三个认证/租户中间件AuthenticationMiddleware令牌校验、提取 user 与 tenant_id、TenancyMiddleware强制执行 tenancy 模式disabled / single / multi、RouteAuthorizationMiddleware路由级访问策略。此外还有RequestMetricsMiddleware请求指标采集、HSTSMiddlewareHTTPS 严格传输安全头、ClientVersionMiddleware基于x-ogx-client-version请求头做 major.minor 版本兼容性校验不兼容时返回 426 Upgrade Required以及ProviderDataMiddleware为所有路由建立请求上下文共同构成完整的服务端中间件栈。路由注册的时机也值得注意StackApp 是 FastAPI 的包装类持有一个Stack实例在 FastAPI 的 lifespan 上下文管理器server.py中先执行app.stack.initialize()完成所有 Provider 的初始化然后才调用build_fastapi_router(api, impl)为每个启用的 API 构建并注册路由器——因为 impl 在Stack.initialize()完成前尚不可用所以路由器注册被有意推迟到 lifespan 阶段。启动时还会创建 registry 刷新后台任务create_registry_refresh_task()配合 stack.py 中的REGISTRY_REFRESH_INTERVAL_SECONDS 300每 5 分钟刷新一次资源注册表。详细流程示例一次 Chat Completion以POST /v1/chat/completions、请求体model: ollama/llama3.2:3b-instruct-fp16为例完整链路如下客户端发送请求server.py将请求分发到 inference 的 FastAPI 路由器InferenceRoutersrc/ogx/core/routers/inference.py调用routing_table.get_provider_impl(model_id)CommonRoutingTableImplsrc/ogx/core/routing_tables/common.py在DistributionRegistry中查找该模型确认它归属于ollamaProvider路由器委托给ollamaProvider 的openai_chat_completion()方法Ollama Provider 继承OpenAIMixinsrc/ogx/providers/utils/inference/openai_mixin.py创建一个指向 Ollama 服务的AsyncOpenAI客户端并转发请求响应以 SSE 事件流的形式经路由器流式返回客户端。这条链路中模型 ID 即路由键的设计provider/model前缀是 OGX 多 Provider 并存的基石同一个 API、同一份协议通过模型名即可精确落到不同的后端。Provider 架构Provider 类型Inline 与 RemoteOGX 将 Provider 划分为两大类型Provider | |-- InlineProviderSpec (runs in-process) | provider_type: inline::builtin | module: ogx.providers.inline.inference.builtin | |-- RemoteProviderSpec (adapts an external service) provider_type: remote::ollama module: ogx.providers.remote.inference.ollamaInline Provider进程内运行例如 meta-reference 推理、sqlite-vec 向量检索实现在 src/ogx/providers/inlineRemote Provider适配外部服务例如 ollama、openai、fireworks 等实现在 src/ogx/providers/remote。每个 Provider 规格ProviderSpec声明以下字段字段含义示例api实现的 API 类型Api.inferenceprovider_type唯一标识符remote::openaimodule提供get_adapter_impl()或get_provider_impl()工厂函数的 Python 模块ogx.providers.remote.inference.ollamaconfig_classProvider 的 Pydantic 配置模型OllamaConfigpip_packages运行时需要的额外依赖ollamaProvider Registry按 API 注册全部可用 Providersrc/ogx/providers/registry 目录下每个 API 对应一个文件如inference.py、responses.py。每个文件定义available_providers()函数返回该 API 下的全部ProviderSpec对象。启动时由 core/distribution.py 的get_provider_registry()统一加载。从 distribution.py 的源码看INTERNAL_APISinspect、providers、prompts、conversations、connectors、admin、containers由内置实现直接服务不属于可配置 Providerprovidable_apis()会排除内部 API 与自动路由表 API只对剩余 API 加载外部可配置 Provider。值得一提的是OGX 还支持通过providers.d/目录以 YAML 文件声明外部 Provider支持remote/api/xxx.yaml与inline/api/xxx.yaml两级结构get_provider_registry()会一并加载这为第三方扩展提供了声明式入口。Provider 解析resolve_impls()四步走启动时core/resolver.py 的resolve_impls()按以下顺序完成 Provider 装配校验validate_and_prepare_providers()将 run config 中声明的 Provider 与注册表比对。特别地若试图为自动路由表 API如Api.models显式配置 Provider会直接抛出ValueError: Provider for {api_str} is automatically provided and cannot be overridden见 resolver.py同时处理弃用deprecation_error直接拒绝、deprecation_warning打警告排序sort_providers_by_deps()基于api_dependencies与optional_api_dependencies做依赖排序如 agents 依赖 inference缺依赖时给出明确的RuntimeError提示实例化instantiate_providers()逐个导入模块并调用工厂函数把实现按Api存入impls字典自动路由装配为 inference 等 API 创建RoutingTableRouter组合使多个 Provider 可以通过同一 API 服务不同模型。instantiate_providers()还有两个值得关注的后处理细节resolver.py一是若同时启用了vector_io与vector_stores会把VectorIORouter注入VectorStoresRoutingTable用于查询改写二是通过set_sibling_providers()把同 API 下的其他 Provider 实现注入当前实例实现 Provider 间的协作。自动路由Auto-Routing许多 API 采用自动路由模式。以Api.inference与其配对的Api.models为例Api.models (RoutingTable) -- Api.inference (Router) | | |-- ModelsRoutingTable |-- InferenceRouter | tracks which provider | delegates to correct | owns which model | provider per request自动路由配对清单由 core/distribution.py 的builtin_automatically_routed_apis()定义Routing Table APIRouter APIApi.modelsApi.inferenceApi.tool_groupsApi.tool_runtimeApi.vector_storesApi.vector_io从 resolver.py 的specs_for_autorouted_apis()可以看到路由表 API 会被注册为provider_type__routing_table__的内置 Provider路由器 API 则注册为provider_type__autorouted__并且vector_io路由器把Api.inference声明为可选依赖——只有 inference 同时启用时向量查询才会具备查询改写能力。这就是同一套 API、多个 Provider 并存的底层机制路由表负责登记哪个 Provider 拥有哪个资源路由器负责按请求把调用分发到正确的 Provider。API 层ogx_api协议即契约ogx_api包定义了全部对外公开的类型与协议包含四类核心内容ProtocolsInference、Responses、Skills等 PythonProtocol类定义了 API 契约HTTP 路由由各fastapi_routes.py模块中的 FastAPI 路由器承载Data Types请求、响应与资源的 Pydantic 模型如Model、VectorStore、ChatCompletionRequestProvider SpecsInlineProviderSpec、RemoteProviderSpec及相关类型定义 Provider 的声明方式Internal utilitiesKVStore与SqlStore的抽象接口放在此包中使得第三方 Provider 无需依赖完整服务端即可使用存储能力。Provider 实现方的依赖关系非常干净从ogx_api导入类型定义从ogx.providers.utils导入共享功能见 src/ogx/providers/utils。这也意味着只要实现ogx_api中声明的Protocol任何第三方代码都能作为 OGX 的 Provider 被加载。存储层KVStore、SqlStore 与租户隔离存储配置存储配置位于 run config 的storage段StackConfig.storage定义 Provider 与核心服务使用的后端引用storage: type: sqlite db_path: ${env.SQLITE_STORE_DIR}/registry.db stores: kvstore: type: kv_sqlite db_path: ${env.SQLITE_STORE_DIR}/kvstore.db inference: type: sql_sqlite db_path: ${env.SQLITE_STORE_DIR}/inference_store.dbKVStore键值存储抽象src/ogx/core/storage/kvstore 提供键值存储抽象KVStore支持多后端后端配置类典型用途SQLiteSqliteKVStoreConfig默认单节点RedisRedisKVStoreConfig多节点、缓存PostgreSQLPostgresKVStoreConfig生产环境部署MongoDBMongoDBKVStoreConfig文档型数据使用方包括distribution registry、配额跟踪quota tracking、Provider 状态、skills 元数据。SqlStoreSQL 存储抽象src/ogx/core/storage/sqlstore 提供基于 SQLAlchemy 的 SQL 存储抽象SqlStore后端配置类典型用途SQLiteSqliteSqlStoreConfig默认单节点PostgreSQLPostgresSqlStoreConfig生产环境部署使用方包括inference store聊天补全日志、conversations对话、prompts提示词。AuthorizedSqlStore 与租户隔离AuthorizedSqlStoresrc/ogx/core/storage/sqlstore/authorized_sqlstore.py在SqlStore之上叠加两层相互独立的强制机制租户隔离Tenant Isolation在任何访问控制检查之前先施加一个不可绕过的WHERE tenant_id ?过滤。当启用租户模式single或multi时每张表都会获得tenant_id列写入时盖上已认证用户的 tenant_id读取与变更都被限定在该租户范围内。在multi模式下若缺少租户上下文则生成10子句——即默认拒绝什么都看不到防止跨租户数据泄露ABAC基于属性的访问控制owner_principal与access_attributes列支撑诸如user is owner的策略规则。它工作在租户内部不跨租户。租户模式在Stack.initialize()期间通过set_default_tenancy_mode()进程级设置因此现有使用authorized_sqlstore()工厂的调用点无需任何改动即可自动获得租户隔离能力。Distribution Registry资源注册中心src/ogx/core/store/registry.py 实现DistributionRegistry跟踪所有已注册资源模型、向量存储、工具组、提示词等归属于哪个 Provider。它持久化到配置的 KVStore因此资源注册信息在服务重启后依然存活。从 stack.py 的RESOURCES列表可以看到models与vector_stores是核心的自动注册资源注册时会附带RegisterModelRequest请求模型以支持配置对象到请求类的自动转换。配置模型Run Config、环境变量与 DistributionsRun ConfigStackConfigRun Config 是一个 YAML 文件定义了一个运行中的 OGX 实例的全部信息version: 2 distro_name: starter apis: - inference - responses - vector_io # ... providers: inference: - provider_id: ollama provider_type: remote::ollama config: base_url: ${env.OLLAMA_URL:http://localhost:11434/v1} storage: type: sqlite db_path: ...关键特性环境变量替换${env.VAR_NAME:default}语法为配置值提供默认值兜底上例中OLLAMA_URL未设置时回退到http://localhost:11434/v1条件 Provider${env.API_KEY:provider_id}语法——仅当变量被设置时才启用对应 Provider每 API 多 Provider例如ollama与openai可同时为 inference 服务各自处理不同模型这正是自动路由发挥作用的场景。配置解析由 src/ogx/core/utils/config_resolution.py 承担resolve_config_or_distro()它决定从显式配置文件还是从发行版distro解析出最终的StackConfig。条件变量未命中时对应资源的 ID 字段会解析为空并被跳过——stack.py 的RESOURCE_ID_FIELDSvector_store_id、model_id专门处理这一情况。Distributions预置发行版Distribution 是为特定目标环境预构建的配置捆绑了具体的 Provider 集合。可以类比 Kubernetes 发行版AKS、EKS、GKE核心 API 保持一致但每个发行版接入了不同的后端。src/ogx/distributions 存放这些配置例如starter、nvidia、oci、watsonx、open-benchmark。每个发行版目录包含config.yaml——run config通过template.py提供的模板与代码生成支持。Build ConfigBuild Config 由ogx build命令用于构建容器镜像声明要包含哪些 Provider、安装哪些包它与 run config分开独立版本管理。录制回放测试系统Record/Replay集成测试使用一套录制/回放系统src/ogx/testing/api_recorder.py先拦截 OpenAI 客户端的调用录制真实 API 响应再在 CI 中回放从而获得快速、确定性的测试运行。工作原理录制Recording测试针对真实服务器运行。APIRecordermonkey-patchOpenAI客户端方法捕获每一对请求/响应响应以 JSON 文件存储在tests/integration/recordings/下回放ReplayCI 中以回放模式运行。记录器通过对请求参数做哈希来匹配存储的响应直接返回缓存响应不再发起真实 API 调用模式Modes由--inference-mode或环境变量OGX_TEST_INFERENCE_MODE控制replay默认——使用缓存响应record——强制录制所有交互record-if-missing——仅在无缓存响应时录制live——完全绕过录制发起真实调用确定性 ID回放期间记录器通过set_id_override()覆盖 ID 生成使文件、向量存储等资源 ID 在多次运行间可复现。录制存储录制文件存放在tests/integration/recordings/按 Provider 与测试组织。每条录制是一个 JSON 文件包含序列化的请求参数与响应另有一个 SQLite 索引负责把请求映射到响应文件。更多细节可参考 tests/README.md 与 tests/integration/README.md。这套机制的价值在于把对真实外部服务的依赖转化为对本地录制数据的确定性回放既保证了集成测试的真实性又让 CI 跑得快、跑得稳。关键类与入口速查表组件位置用途OGXcore/stack.py实现全部 API 协议的复合类Stackcore/stack.py初始化、资源注册、生命周期StackAppcore/server/server.pyFastAPI 应用包装类resolve_impls()core/resolver.pyProvider 实例化与依赖解析CommonRoutingTableImplcore/routing_tables/common.py所有自动路由 API 的基类路由表InferenceRoutercore/routers/inference.py将推理调用路由到正确 ProviderOpenAIMixinproviders/utils/inference/openai_mixin.py共享的 OpenAI 兼容客户端逻辑get_provider_registry()core/distribution.py加载全部可用 Provider 规格APIRecordertesting/api_recorder.py录制/回放测试基础设施目录地图一张图定位所有代码src/ ogx_api/ # API 定义包独立 pip 包 inference/ # Inference 协议、模型、FastAPI 路由 responses/ # Responses API 协议与路由 datatypes.py # 共享数据类型 providers/ # Provider 规格类型 internal/ # KVStore/SqlStore 接口 ogx/ # 服务端实现 core/ server/ # FastAPI 服务端、认证、路由 routers/ # API 专属路由器inference、responses 等 routing_tables/ # 资源到 Provider 的映射 storage/ # KVStore 与 SqlStore 后端 store/ # Distribution registry resolver.py # Provider 解析引擎 distribution.py # Provider 注册表加载 stack.py # Stack 初始化与生命周期 providers/ inline/ # 进程内 Provider 实现 remote/ # 远程服务适配器 registry/ # Provider 规格声明 utils/ # 共享 Provider 工具 distributions/ # 预置发行版配置 cli/ # CLI 命令ogx stack run、build 等 testing/ # 测试基础设施api_recorder tests/ unit/ # 快速、隔离的单元测试 integration/ # 录制/回放的端到端测试 recordings/ # 缓存的 API 响应对于希望深入代码库的贡献者或 AI Agent建议按此路径阅读先看 ARCHITECTURE.md 建立全局认知再依次阅读core/stack.py生命周期与组合、core/resolver.pyProvider 装配、core/routers/inference.py与core/routing_tables/common.py自动路由机制最后用 tests/integration 的录制回放测试验证对请求链路的理解。OGX 的架构核心可以浓缩为一句话协议在ogx_api装配在ogx.core执行在 Provider而这一切通过自动路由这张资源所有权表统一起来——理解了这一条主线其余细节皆可顺藤摸瓜。【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考