OGX 发行版Distribution完全指南预构建 Provider 配置、模板生成与持久化开关【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogxOGXOpen GenAI Stack通过发行版Distribution机制把API 网关核心与面向具体环境的 Provider 组合解耦核心 API 保持一致后端按需插拔。本文基于 src/ogx/distributions/README.md 及仓库源码系统讲解发行版的概念、目录结构、配置语法、模板生成引擎以及如何用环境变量裁剪 Provider、关闭聊天补全持久化读完即可自己编写并运行一套定制发行版。什么是发行版Distribution发行版是一套预构建的配置它把特定 Provider 绑定到目标运行环境类似于 Kubernetes 世界里 AKS、EKS、GKE 之于 K8s 的关系——K8s 核心 API 不变但每个发行版接入了不同的后端与配套工具链。在 OGX 中一个发行版具体就是一个config.yaml文件它定义了apis对外提供哪些 API如inference、responses、vector_io等providers每个 API 使用哪些 Provider远程云服务或本地内联实现storageKV 存储与 SQL 存储的后端类型、表结构、写入队列参数registered_resources启动时要注册的模型、向量库等资源。一个最小示例取自 starter/config.yamlversion: 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}version: 2表示运行配置的 schema 版本与 src/ogx/core/datatypes.py 中的OGX_RUN_CONFIG_VERSION对应distro_name用于标记配置归属的发行版。目录结构与内置发行版仓库中发行版目录位于 src/ogx/distributions/每个子目录对应一种常见部署场景distributions/ starter/ # 通用发行版启用大量 ProviderCPU 环境快速起步 ci-tests/ # CI 测试用的最小增强发行版含认证/多租户开关 nvidia/ # 基于 NVIDIA NIM 的发行版 oci/ # Oracle Cloud Infrastructure 发行版 open-benchmark/ # 基准测试发行版 postgres-demo/ # 以 PostgreSQL 为存储后端的演示发行版 watsonx/ # IBM WatsonX 发行版 __init__.py template.py # 发行版模板渲染引擎各目录除了config.yaml之外通常还包含同名 Python 模块如starter.py由get_distribution_template()函数返回DistributionTemplate实例作为config.yaml的生成源。各发行版定位速览发行版核心 Provider适用场景starter15 个远程推理 ProviderOpenAI、Anthropic、Gemini、Groq、vLLM、Ollama 等 9 个向量库 内置工具通用开发/演示CPU 环境即可运行ci-testsstarter 全集 WatsonX并预注册测试 MCP 连接器自动化测试验证认证与多租户配置nvidiaremote::nvidia faiss file-searchNVIDIA NIM 生态ociremote::oci实例主体验证Oracle Cloud 部署open-benchmarkOpenAI/Anthropic/Gemini/Groq/Together sqlite-vec 等负载/对比基准测试watsonxremote::watsonxIBM 云IBM 云环境postgres-demostarter 基础上切换 PostgreSQL 存储展示 Postgres 后端值得注意的是各发行版的config.yaml头部都会列出apis例如 starter 启用了batches、file_processors、files、inference、interactions、messages、responses、skills、tool_runtime、vector_io共 10 个 API而 nvidia/config.yaml 只保留 5 个体现了按需裁剪的设计哲学。环境变量替换语法发行版配置使用${env.VAR:default}语法实现环境驱动的配置这是 OGX 配置最核心的机制两种形态语义不同${env.VAR:default}读取环境变量VAR若未设置则使用default作为回退值。例如base_url: ${env.OLLAMA_URL:http://localhost:11434/v1}表示 Ollama 未配置 URL 时默认连本地 11434 端口。${env.VAR:value}条件启用——仅当环境变量VAR被设置非空时该项才生效。语法通常直接用在provider_id上实现环境变量存在才注册该 Providerproviders: inference: - provider_id: ${env.CEREBRAS_API_KEY:cerebras} provider_type: remote::cerebras config: base_url: https://api.cerebras.ai/v1 api_key: ${env.CEREBRAS_API_KEY:} - provider_id: ${env.OLLAMA_URL:ollama} provider_type: remote::ollama config: base_url: ${env.OLLAMA_URL:http://localhost:11434/v1}从 starter/starter.py 的INFERENCE_PROVIDER_IDS字典可以看出Ollama、vLLM、Cerebras、NVIDIA、Vertex AI、Azure 这 6 家 Provider 的provider_id都带${env...:...}条件前缀未配置对应环境变量时它们不会出现在最终配置中而 OpenAI、Anthropic、Gemini 等则始终注册只是 key 为空时调用会失败。starter 发行版关键环境变量依据 starter.py 中的run_config_env_vars声明环境变量默认值说明OGX_PORT8321发行版服务端口OLLAMA_URLhttp://localhost:11434Ollama 服务地址VLLM_URLhttp://localhost:8000/v1vLLM 服务地址VLLM_INFERENCE_MODEL空启动时注册的 vLLM 模型FIREWORKS_API_KEY/OPENAI_API_KEY/GROQ_API_KEY/META_API_KEY/ANTHROPIC_API_KEY/GEMINI_API_KEY/SAMBANOVA_API_KEY空各家云推理密钥VERTEX_AI_PROJECT/VERTEX_AI_LOCATION空 /globalVertex AI 项目与区域AZURE_API_KEY/AZURE_API_BASE/AZURE_API_VERSION/AZURE_API_TYPE空 / 空 / 空 /azureAzure OpenAI 接入参数INFINISPAN_URL/INFINISPAN_USERNAME/INFINISPAN_PASSWORDhttp://localhost:11222/admin/ 空Infinispan 向量库认证模板系统从 Python 模板到 config.yamltemplate.py提供DistributionTemplate类用于程序化生成发行版配置。每个发行版目录下的 Python 模块定义模板随后由 scripts/distro_codegen.py 扫描src/ogx/distributions/下各子目录、导入模块、调用get_distribution_template()再把生成的config.yaml写回对应目录并将渲染后的文档写入docs/docs/distributions/下对应 distro_type 目录。DistributionTemplate 核心结构从 template.py 源码看模板对象包含class DistributionTemplate(BaseModel): name: str # 发行版名称 description: str # 描述也用于生成文档 distro_type: Literal[self_hosted, remote_hosted, ondevice] providers: dict[str, list[BuildProvider]] # API - Provider 构建规格 run_configs: dict[str, RunConfigSettings] # 输出配置文件名 - 生成设置 template_path: Path | None None # 文档模板Jinja2 run_config_env_vars: dict[str, tuple[str, str]] | None None container_image: str | None None available_models_by_provider: dict[str, list[ProviderModelEntry]] | None None配置生成的自动化流程RunConfigSettings.run_config()是核心生成逻辑关键步骤包括校验 Provider 合法性对每个 API 的 Provider检查provider_type是否存在于 provider registryget_provider_registry()未知类型直接抛ValueError填充 Provider 默认配置通过config_class.sample_run_config(...)获取各 Provider 适配器的示例配置注入默认存储层默认生成 SQLite 后端——kv_defaultkvstore.db与sql_defaultsql_store.db并挂载metadata、inference、conversations、prompts、connectors等 store 引用汇总输出结构组装version、distro_name、apis、providers、storage、registered_resources、server.port默认 8321等顶层字段并可选注入auth_config、tenancy_config、vector_stores_config与connectors。生成 YAML 时还会调用filter_empty_values()递归清理空module字段、空config字典和空的container_image保证产物干净。模型 ID 冲突处理get_model_registry()会汇总各 Provider 的模型清单并检查provider_model_id与 alias 的 ID 冲突一旦发现冲突会打印黄色警告Model id xxx conflicts; all model ids will be prefixed with provider id并将所有模型 ID 统一加provider_id/前缀以消除歧义。starter 模板示例starter/starter.py 演示了如何组合这些能力它从available_providers()中筛选RemoteProviderSpec类型的远程推理 ProviderENABLED_INFERENCE_PROVIDERS白名单过滤再叠加内联的sentence-transformers嵌入模型、faiss/sqlite-vec/milvus 等向量库、file-search 与 MCP 工具运行时最终生成两个运行配置run_configs{ config.yaml: base_run_settings, run-with-postgres-store.yaml: postgres_run_settings, },其中postgres_run_settings通过model_copy(update{storage_backends: {...}}, deepTrue)把 SQLite 后端替换为PostgresKVStoreConfig/PostgresSqlStoreConfig——这就是 run-with-postgres-store.yaml 的来源。另外 starter 还预注册了 3 个 Claude 模型别名provider_id: all、provider_model_id: auto从源码注释看这是为了零配置兼容 Claude Code。ci-tests面向测试的模板覆写ci-tests/ci_tests.py 展示了如何在 starter 基础上做增量定制直接复用get_starter_distribution_template(nameci-tests)然后预注册test-mcp-connectorhttp://localhost:5199/sse供test_response_connector_resolution_mcp_tool使用预注册 Azure、WatsonX、Vertex AI、Bedrock 四家模型——源码注释说明原因录制recording系统无法在 CI 中回放这些端点的模型列表发现调用追加 WatsonX 推理 Provider并把sentence-transformers的trust_remote_code置为true追加环境变量门控的认证配置AUTH_PROVIDER未设置时认证关闭与多租户配置OGX_TENANCY_MODE:disabled默认关闭。这套模板继承 覆写模式非常适合团队基于官方发行版二次定制。运行发行版启动一个发行版有两种方式见 distributions/README.mdogx run starter # 或显式指定配置文件 ogx stack run --config path/to/config.yamlogx run distro_name会从~/.ogx/distributions/解析对应发行版注意配置中的默认路径如~/.ogx/distributions/starter/kvstore.db均指向该目录ogx stack run --config则直接加载任意config.yaml适合运行自定义配置或非内置发行版。服务默认监听 8321 端口server.port。关闭 Chat Completions 持久化默认情况下inferencestore 引用处于启用状态因此聊天补全请求/响应负载会被持久化历史类接口list、retrieve、messages都从该 store 提供服务。操作员可以通过在运行配置中设置inference.enabled: false来关闭这一持久化storage: stores: inference: enabled: false关闭后的行为细节从 distributions/README.md 与 src/ogx/core/storage/README.md 的说明可知不再构造InferenceStore不会创建inference_store表也不运行后台写入 worker推理功能不受影响流式与非流式的聊天补全照常工作历史接口语义变化历史类端点返回HTTP 501未配置持久化而不是返回空列表或 404——避免查不到历史与功能损坏被混淆隔离性responses、datasets、eval、files、prompts、vector_io等其他 store 保持启用关闭 inference 持久化与存储层其余部分完全独立。对比各发行版配置可以发现inferencestore 的典型形态如 starter/config.yaml包含max_write_queue_size: 10000与num_writers: 4——前者控制写入队列上限后者决定后台落盘 worker 数量这也是关闭该 store 后不再存在的两个后台资源。结语OGX 发行版机制的核心价值在于一份核心、多套接线config.yaml是运行时契约DistributionTemplate是生成契约的引擎${env.VAR:default}/${env.VAR:value}让配置随环境自适应inference.enabled: false让持久化可按需裁剪。无论是开箱即用的 starter还是面向 NVIDIA、OCI、WatsonX、基准测试的专用发行版这套模式都让你能在不改动核心 API 的前提下为任意目标环境快速定制一套 OGX 网关。想继续深入可阅读 template.py、starter.py 以及 distro_codegen.py 了解完整的生成链路。【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OGX 发行版（Distribution）完全指南：预构建 Provider 配置、模板生成与持久化开关
OGX 发行版Distribution完全指南预构建 Provider 配置、模板生成与持久化开关【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogxOGXOpen GenAI Stack通过发行版Distribution机制把API 网关核心与面向具体环境的 Provider 组合解耦核心 API 保持一致后端按需插拔。本文基于 src/ogx/distributions/README.md 及仓库源码系统讲解发行版的概念、目录结构、配置语法、模板生成引擎以及如何用环境变量裁剪 Provider、关闭聊天补全持久化读完即可自己编写并运行一套定制发行版。什么是发行版Distribution发行版是一套预构建的配置它把特定 Provider 绑定到目标运行环境类似于 Kubernetes 世界里 AKS、EKS、GKE 之于 K8s 的关系——K8s 核心 API 不变但每个发行版接入了不同的后端与配套工具链。在 OGX 中一个发行版具体就是一个config.yaml文件它定义了apis对外提供哪些 API如inference、responses、vector_io等providers每个 API 使用哪些 Provider远程云服务或本地内联实现storageKV 存储与 SQL 存储的后端类型、表结构、写入队列参数registered_resources启动时要注册的模型、向量库等资源。一个最小示例取自 starter/config.yamlversion: 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}version: 2表示运行配置的 schema 版本与 src/ogx/core/datatypes.py 中的OGX_RUN_CONFIG_VERSION对应distro_name用于标记配置归属的发行版。目录结构与内置发行版仓库中发行版目录位于 src/ogx/distributions/每个子目录对应一种常见部署场景distributions/ starter/ # 通用发行版启用大量 ProviderCPU 环境快速起步 ci-tests/ # CI 测试用的最小增强发行版含认证/多租户开关 nvidia/ # 基于 NVIDIA NIM 的发行版 oci/ # Oracle Cloud Infrastructure 发行版 open-benchmark/ # 基准测试发行版 postgres-demo/ # 以 PostgreSQL 为存储后端的演示发行版 watsonx/ # IBM WatsonX 发行版 __init__.py template.py # 发行版模板渲染引擎各目录除了config.yaml之外通常还包含同名 Python 模块如starter.py由get_distribution_template()函数返回DistributionTemplate实例作为config.yaml的生成源。各发行版定位速览发行版核心 Provider适用场景starter15 个远程推理 ProviderOpenAI、Anthropic、Gemini、Groq、vLLM、Ollama 等 9 个向量库 内置工具通用开发/演示CPU 环境即可运行ci-testsstarter 全集 WatsonX并预注册测试 MCP 连接器自动化测试验证认证与多租户配置nvidiaremote::nvidia faiss file-searchNVIDIA NIM 生态ociremote::oci实例主体验证Oracle Cloud 部署open-benchmarkOpenAI/Anthropic/Gemini/Groq/Together sqlite-vec 等负载/对比基准测试watsonxremote::watsonxIBM 云IBM 云环境postgres-demostarter 基础上切换 PostgreSQL 存储展示 Postgres 后端值得注意的是各发行版的config.yaml头部都会列出apis例如 starter 启用了batches、file_processors、files、inference、interactions、messages、responses、skills、tool_runtime、vector_io共 10 个 API而 nvidia/config.yaml 只保留 5 个体现了按需裁剪的设计哲学。环境变量替换语法发行版配置使用${env.VAR:default}语法实现环境驱动的配置这是 OGX 配置最核心的机制两种形态语义不同${env.VAR:default}读取环境变量VAR若未设置则使用default作为回退值。例如base_url: ${env.OLLAMA_URL:http://localhost:11434/v1}表示 Ollama 未配置 URL 时默认连本地 11434 端口。${env.VAR:value}条件启用——仅当环境变量VAR被设置非空时该项才生效。语法通常直接用在provider_id上实现环境变量存在才注册该 Providerproviders: inference: - provider_id: ${env.CEREBRAS_API_KEY:cerebras} provider_type: remote::cerebras config: base_url: https://api.cerebras.ai/v1 api_key: ${env.CEREBRAS_API_KEY:} - provider_id: ${env.OLLAMA_URL:ollama} provider_type: remote::ollama config: base_url: ${env.OLLAMA_URL:http://localhost:11434/v1}从 starter/starter.py 的INFERENCE_PROVIDER_IDS字典可以看出Ollama、vLLM、Cerebras、NVIDIA、Vertex AI、Azure 这 6 家 Provider 的provider_id都带${env...:...}条件前缀未配置对应环境变量时它们不会出现在最终配置中而 OpenAI、Anthropic、Gemini 等则始终注册只是 key 为空时调用会失败。starter 发行版关键环境变量依据 starter.py 中的run_config_env_vars声明环境变量默认值说明OGX_PORT8321发行版服务端口OLLAMA_URLhttp://localhost:11434Ollama 服务地址VLLM_URLhttp://localhost:8000/v1vLLM 服务地址VLLM_INFERENCE_MODEL空启动时注册的 vLLM 模型FIREWORKS_API_KEY/OPENAI_API_KEY/GROQ_API_KEY/META_API_KEY/ANTHROPIC_API_KEY/GEMINI_API_KEY/SAMBANOVA_API_KEY空各家云推理密钥VERTEX_AI_PROJECT/VERTEX_AI_LOCATION空 /globalVertex AI 项目与区域AZURE_API_KEY/AZURE_API_BASE/AZURE_API_VERSION/AZURE_API_TYPE空 / 空 / 空 /azureAzure OpenAI 接入参数INFINISPAN_URL/INFINISPAN_USERNAME/INFINISPAN_PASSWORDhttp://localhost:11222/admin/ 空Infinispan 向量库认证模板系统从 Python 模板到 config.yamltemplate.py提供DistributionTemplate类用于程序化生成发行版配置。每个发行版目录下的 Python 模块定义模板随后由 scripts/distro_codegen.py 扫描src/ogx/distributions/下各子目录、导入模块、调用get_distribution_template()再把生成的config.yaml写回对应目录并将渲染后的文档写入docs/docs/distributions/下对应 distro_type 目录。DistributionTemplate 核心结构从 template.py 源码看模板对象包含class DistributionTemplate(BaseModel): name: str # 发行版名称 description: str # 描述也用于生成文档 distro_type: Literal[self_hosted, remote_hosted, ondevice] providers: dict[str, list[BuildProvider]] # API - Provider 构建规格 run_configs: dict[str, RunConfigSettings] # 输出配置文件名 - 生成设置 template_path: Path | None None # 文档模板Jinja2 run_config_env_vars: dict[str, tuple[str, str]] | None None container_image: str | None None available_models_by_provider: dict[str, list[ProviderModelEntry]] | None None配置生成的自动化流程RunConfigSettings.run_config()是核心生成逻辑关键步骤包括校验 Provider 合法性对每个 API 的 Provider检查provider_type是否存在于 provider registryget_provider_registry()未知类型直接抛ValueError填充 Provider 默认配置通过config_class.sample_run_config(...)获取各 Provider 适配器的示例配置注入默认存储层默认生成 SQLite 后端——kv_defaultkvstore.db与sql_defaultsql_store.db并挂载metadata、inference、conversations、prompts、connectors等 store 引用汇总输出结构组装version、distro_name、apis、providers、storage、registered_resources、server.port默认 8321等顶层字段并可选注入auth_config、tenancy_config、vector_stores_config与connectors。生成 YAML 时还会调用filter_empty_values()递归清理空module字段、空config字典和空的container_image保证产物干净。模型 ID 冲突处理get_model_registry()会汇总各 Provider 的模型清单并检查provider_model_id与 alias 的 ID 冲突一旦发现冲突会打印黄色警告Model id xxx conflicts; all model ids will be prefixed with provider id并将所有模型 ID 统一加provider_id/前缀以消除歧义。starter 模板示例starter/starter.py 演示了如何组合这些能力它从available_providers()中筛选RemoteProviderSpec类型的远程推理 ProviderENABLED_INFERENCE_PROVIDERS白名单过滤再叠加内联的sentence-transformers嵌入模型、faiss/sqlite-vec/milvus 等向量库、file-search 与 MCP 工具运行时最终生成两个运行配置run_configs{ config.yaml: base_run_settings, run-with-postgres-store.yaml: postgres_run_settings, },其中postgres_run_settings通过model_copy(update{storage_backends: {...}}, deepTrue)把 SQLite 后端替换为PostgresKVStoreConfig/PostgresSqlStoreConfig——这就是 run-with-postgres-store.yaml 的来源。另外 starter 还预注册了 3 个 Claude 模型别名provider_id: all、provider_model_id: auto从源码注释看这是为了零配置兼容 Claude Code。ci-tests面向测试的模板覆写ci-tests/ci_tests.py 展示了如何在 starter 基础上做增量定制直接复用get_starter_distribution_template(nameci-tests)然后预注册test-mcp-connectorhttp://localhost:5199/sse供test_response_connector_resolution_mcp_tool使用预注册 Azure、WatsonX、Vertex AI、Bedrock 四家模型——源码注释说明原因录制recording系统无法在 CI 中回放这些端点的模型列表发现调用追加 WatsonX 推理 Provider并把sentence-transformers的trust_remote_code置为true追加环境变量门控的认证配置AUTH_PROVIDER未设置时认证关闭与多租户配置OGX_TENANCY_MODE:disabled默认关闭。这套模板继承 覆写模式非常适合团队基于官方发行版二次定制。运行发行版启动一个发行版有两种方式见 distributions/README.mdogx run starter # 或显式指定配置文件 ogx stack run --config path/to/config.yamlogx run distro_name会从~/.ogx/distributions/解析对应发行版注意配置中的默认路径如~/.ogx/distributions/starter/kvstore.db均指向该目录ogx stack run --config则直接加载任意config.yaml适合运行自定义配置或非内置发行版。服务默认监听 8321 端口server.port。关闭 Chat Completions 持久化默认情况下inferencestore 引用处于启用状态因此聊天补全请求/响应负载会被持久化历史类接口list、retrieve、messages都从该 store 提供服务。操作员可以通过在运行配置中设置inference.enabled: false来关闭这一持久化storage: stores: inference: enabled: false关闭后的行为细节从 distributions/README.md 与 src/ogx/core/storage/README.md 的说明可知不再构造InferenceStore不会创建inference_store表也不运行后台写入 worker推理功能不受影响流式与非流式的聊天补全照常工作历史接口语义变化历史类端点返回HTTP 501未配置持久化而不是返回空列表或 404——避免查不到历史与功能损坏被混淆隔离性responses、datasets、eval、files、prompts、vector_io等其他 store 保持启用关闭 inference 持久化与存储层其余部分完全独立。对比各发行版配置可以发现inferencestore 的典型形态如 starter/config.yaml包含max_write_queue_size: 10000与num_writers: 4——前者控制写入队列上限后者决定后台落盘 worker 数量这也是关闭该 store 后不再存在的两个后台资源。结语OGX 发行版机制的核心价值在于一份核心、多套接线config.yaml是运行时契约DistributionTemplate是生成契约的引擎${env.VAR:default}/${env.VAR:value}让配置随环境自适应inference.enabled: false让持久化可按需裁剪。无论是开箱即用的 starter还是面向 NVIDIA、OCI、WatsonX、基准测试的专用发行版这套模式都让你能在不改动核心 API 的前提下为任意目标环境快速定制一套 OGX 网关。想继续深入可阅读 template.py、starter.py 以及 distro_codegen.py 了解完整的生成链路。【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考