企业官网建设流程全解析

OGX 发行版（Distribution）完全指南：预构建 Provider 配置、模板生成与持久化开关

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

OGX（Open 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（远程云服务或本地内联实现）；
• storage：KV 存储与 SQL 存储的后端类型、表结构、写入队列参数；
• registered_resources：启动时要注册的模型、向量库等资源。

一个最小示例（取自 starter/config.yaml）：

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}

version: 2表示运行配置的 schema 版本，与 src/ogx/core/datatypes.py 中的OGX_RUN_CONFIG_VERSION对应；distro_name用于标记配置归属的发行版。

目录结构与内置发行版

仓库中发行版目录位于 src/ogx/distributions/，每个子目录对应一种常见部署场景：

distributions/ starter/ # 通用发行版，启用大量 Provider（CPU 环境快速起步） 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的"生成源"。

各发行版定位速览

值得注意的是，各发行版的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上，实现"环境变量存在才注册该 Provider"：

providers: 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声明：

模板系统：从 Python 模板到 config.yaml

template.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()是核心生成逻辑，关键步骤包括：

1. 校验 Provider 合法性：对每个 API 的 Provider，检查provider_type是否存在于 provider registry（get_provider_registry()），未知类型直接抛ValueError；
2. 填充 Provider 默认配置：通过config_class.sample_run_config(...)获取各 Provider 适配器的示例配置；
3. 注入默认存储层：默认生成 SQLite 后端——kv_default（kvstore.db）与sql_default（sql_store.db），并挂载metadata、inference、conversations、prompts、connectors等 store 引用；
4. 汇总输出结构：组装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类型的远程推理 Provider（ENABLED_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": {...}}, deep=True)把 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(name="ci-tests")，然后：

• 预注册test-mcp-connector（http://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.md：

ogx run starter # 或显式指定配置文件 ogx stack run --config path/to/config.yaml

ogx 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