OGX NVIDIA Distribution 实战指南接入 NVIDIA NIM 运行 LLM 推理、评测与向量检索【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogxOGXOpen GenAI Stack的 NVIDIA Distribution 是一套预构建的分发配置它将 NVIDIA NIM 推理、NeMo 微服务平台Data Store、Evaluator与 OGX 内置的本地组件FAISS 向量库、本地文件系统、内置 Responses 处理编排在一起开箱即用地提供推理、文件、向量检索、工具调用等 API。阅读本文后你将掌握 NVIDIA Distribution 的完整配置结构、环境变量语义、NIM 部署与删除方法并能够在 Docker 或本地 venv 环境中把 OGX 与 NVIDIA 服务端到端跑通。分发Distribution是什么NVIDIA NIM 推理分发在 OGX 中Distribution 是面向特定部署场景预构建的配置集合其本质是一份config.yaml它定义了需要对外提供哪些 API、每个 API 使用哪个 provider、存储如何组织以及启动时需要注册哪些模型与资源参见 src/ogx/distributions/README.md。NVIDIA Distribution 在 src/ogx/distributions/nvidia/nvidia.py 中被定义为return DistributionTemplate( namename, distro_typeself_hosted, descriptionUse NVIDIA NIM for running LLM inference, ... )其定位是“使用 NVIDIA NIM 运行 LLM 推理”的自托管分发对应的构建产物为ogxai/distribution-nvidia容器镜像。它对外暴露的 API 集合定义在 src/ogx/distributions/nvidia/config.yamlversion: 2 distro_name: nvidia apis: - files - inference - responses - tool_runtime - vector_io即该分发默认启用文件、推理、Responses、工具运行时和向量存储五类 API。Provider 构成与核心配置config.yaml中的providers段决定了每个 API 背后的实现。NVIDIA Distribution 采用“远程 NVIDIA 服务 本地内联组件”混合架构APIprovider_idprovider_type说明inferencenvidiaremote::nvidia调用 NVIDIA NIM托管或自托管完成推理vector_iofaissinline::faiss本地 FAISS 向量库持久化到kv_defaultresponsesbuiltininline::builtin内置 Responses 实现落库到sql_defaulttool_runtimefile-searchinline::file-search文件检索工具运行时filesbuiltin-filesinline::localfs本地文件系统存储目录由FILES_STORAGE_DIR控制其中 inference provider 的完整配置为providers: inference: - provider_id: nvidia provider_type: remote::nvidia config: base_url: ${env.NVIDIA_BASE_URL:https://integrate.api.nvidia.com/v1} api_key: ${env.NVIDIA_API_KEY:}${env.VAR:default}是 OGX 分发配置统一采用的环境变量替换语法未设置该变量时自动回落到:后的默认值。这意味着不设置NVIDIA_BASE_URL时推理请求会默认发往 NVIDIA 托管的预览 APIhttps://integrate.api.nvidia.com/v1如果你自托管 NIM只需把该变量指向你自己的 NIM 端点。存储层默认使用 SQLitekv_sqlite与sql_sqlite数据库文件统一落在~/.ogx/distributions/nvidia/下可通过SQLITE_STORE_DIR重定向storage: backends: kv_default: type: kv_sqlite db_path: ${env.SQLITE_STORE_DIR:~/.ogx/distributions/nvidia}/kvstore.db sql_default: type: sql_sqlite db_path: ${env.SQLITE_STORE_DIR:~/.ogx/distributions/nvidia}/sql_store.db stores: metadata: namespace: registry backend: kv_default inference: table_name: inference_store backend: sql_default max_write_queue_size: 10000 num_writers: 4 enabled: trueinferencestore 默认启用chat completion 的请求/响应会被异步落库写队列上限 10000、4 个写线程从而支撑历史会话查询如需关闭该持久化可将inference.enabled置为false。默认注册模型分发启动时会注册一个默认的 LLM 模型模型 ID 由INFERENCE_MODEL环境变量注入registered_resources: models: - metadata: {} model_id: ${env.INFERENCE_MODEL} provider_id: nvidia model_type: llm环境变量一览NVIDIA Distribution 模板在 src/ogx/distributions/nvidia/nvidia.py 中声明了如下运行配置环境变量变量说明默认值NVIDIA_API_KEYNVIDIA API Key空必填NVIDIA_APPEND_API_VERSION是否在 base_url 后追加 API 版本号TrueINFERENCE_MODEL默认注册的推理模型Llama3.1-8B-Instruct结合config.yaml中的引用实际可配置变量还包括NVIDIA_BASE_URLNVIDIA NIM 端点默认https://integrate.api.nvidia.com/v1托管预览 APIFILES_STORAGE_DIR本地文件存储目录默认~/.ogx/distributions/nvidia/filesSQLITE_STORE_DIRSQLite 数据库目录默认~/.ogx/distributions/nvidia。此外在与 NeMo 微服务对接时还需设置NVIDIA_DATASETS_URLNeMo Data Store 端点与NVIDIA_EVALUATOR_URLNeMo Evaluator 端点详见下文。前置条件NVIDIA API Key使用 NVIDIA 托管 NIM 前请前往 NVIDIA Build 平台build.nvidia.com获取 API Key并将其配置到NVIDIA_API_KEY环境变量中。托管端点要求必须携带 API Key否则推理请求无法鉴权通过。部署 NeMo Microservices PlatformNVIDIA NeMo 微服务平台支持通过 NeMo Microservices Helm Chart 在你的 Kubernetes 集群上端到端部署完整 AI 工作流微服务形式。平台级前置条件GPU 驱动、K8s 集群资源、Helm 安装步骤等请参考 NVIDIA 官方 NeMo Microservices 文档进行安装与部署。OGX 侧只需知道各微服务暴露的端点并通过环境变量接入。支持的 NeMo 微服务NIM、Data Store 与 EvaluatorNVIDIA Distribution 中每个 OGX API 对应一个特定的 NeMo 微服务其中核心微服务Customizer、Evaluator暴露在同一个端点而平台组件Data Store则各自拥有独立端点。从源码结构看推理适配器定义于 src/ogx/providers/remote/inference/nvidia/其实现细节与本文各服务的映射关系如下。Inference APINVIDIA NIMNVIDIA NIM 负责对已注册模型执行推理有两种访问方式托管默认使用托管在https://integrate.api.nvidia.com的预览 API需要 API Key自托管在你自己的基础设施上运行 NVIDIA NIM。部署平台后NIM Proxy 微服务即为访问你自托管 NIM 的统一入口例如对模型执行推理。使用自托管模式时将NVIDIA_BASE_URL环境变量设置为你的 NIM Proxy 部署地址即可。在 src/ogx/providers/remote/inference/nvidia/config.py 的NVIDIAConfig中两种模式被显式区分默认base_url指向托管端点https://integrate.api.nvidia.com/v1需要 API Key自托管时设置自定义 URL且无需 API Key。该逻辑在适配器initialize中做了防护当检测到使用托管端点却缺少 API Key 时会输出错误日志提示“API key is required for hosted NVIDIA NIM”。具体判定由utils.py中的_is_nvidia_hosted(config)完成。此外NVIDIAConfig还支持timeoutHTTP 请求超时默认 60 秒与rerank_model_to_urlrerank 模型 ID 到端点的映射。值得注意的是该适配器NVIDIAInferenceAdapter见 src/ogx/providers/remote/inference/nvidia/nvidia.py除标准 chat/completions 外还实现了rerank能力托管模式下请求命中rerank_model_to_url中配置的模型如nv-rerank-qa-mistral-4b:1、nvidia/llama-3.2-nv-rerankqa-1b-v2时会自动切换到对应的 NVIDIA 检索重排端点同时内置了多款 embed 模型的元数据维度与上下文长度如nvidia/llama-3.2-nv-embedqa-1b-v22048 维 / 8192 上下文。这意味着该分发天然支持基于 NIM 的向量化与重排检索链路。Datasetio APINeMo Data StoreNeMo Data Store 微服务是 NeMo 微服务平台默认的文件存储方案。它暴露与 Hugging Face Hub 客户端HfApi兼容的 API因此你可以直接使用HfApi客户端与 Data Store 交互。请将NVIDIA_DATASETS_URL环境变量指向你的 NeMo Data Store 端点。Eval APINeMo EvaluatorNeMo Evaluator 微服务负责对 LLM 进行评估。在 NeMo Evaluator 中启动 Evaluation job 需要一个 Evaluation Config包含 job 所需的元数据对象OGX 的 Benchmark 与 Evaluation Config 一一映射——注册一个 Benchmark 即会在 NeMo Evaluator 中创建一个 Evaluation Config。请将NVIDIA_EVALUATOR_URL环境变量指向你的 NeMo Microservices 端点。部署模型通过 NIM Proxy 下发 NIM要使用已注册模型调用 OGX API需确保对应的 NIM 已部署到你的环境中。以下示例通过 NIM Proxy 微服务部署meta/llama-3.2-1b-instruct# URL to NeMo NIM Proxy service export NEMO_URLhttp://nemo.test curl --location $NEMO_URL/v1/deployment/model-deployments \ -H accept: application/json \ -H Content-Type: application/json \ -d { name: llama-3.2-1b-instruct, namespace: meta, config: { model: meta/llama-3.2-1b-instruct, nim_deployment: { image_name: nvcr.io/nim/meta/llama-3.2-1b-instruct, image_tag: 1.8.3, pvc_size: 25Gi, gpu: 1, additional_envs: { NIM_GUIDED_DECODING_BACKEND: fast_outlines } } } }请求体要点name/namespaceNIM 部署的名称与命名空间nim_deployment.image_name/image_tagNVIDIA 容器仓库nvcr.io中 NIM 镜像及其版本pvc_size为模型权重申请的持久卷大小gpu分配的 GPU 数量NIM_GUIDED_DECODING_BACKENDfast_outlines启用fast_outlines引导解码系统以获得更快的推理速度。注意为获得更优的推理速度应使用带fast_outlines引导解码系统的 NIM在请求体中指定。如果你通过 NeMo Microservices Helm Chart 部署平台该选项默认开启。NIM 部署大约需要 10 分钟生效。如需释放 GPU 资源可通过 DELETE 请求删除已部署的 NIMexport NEMO_URLhttp://nemo.test curl -X DELETE $NEMO_URL/v1/deployment/model-deployments/meta/llama-3.1-8b-instruct运行 OGX with NVIDIA运行 NVIDIA Distribution 有两条路径使用预构建镜像的 Docker 方式无需本地构建代码或基于源码的 venv 方式。方式一DockerOGX_PORT8321 docker run \ -it \ --pull always \ -p $OGX_PORT:$OGX_PORT \ -v ~/.ogx:/root/.ogx \ -e NVIDIA_API_KEY$NVIDIA_API_KEY \ ogxai/distribution-nvidia \ --port $OGX_PORT要点-v ~/.ogx:/root/.ogx将本地数据目录挂载进容器持久化存储、配置与凭据-e NVIDIA_API_KEY$NVIDIA_API_KEY透传 API Key容器默认监听 8321 端口通过--port可自定义。方式二Docker 自定义运行配置如需使用自定义的 run configuration 文件如修改 provider 或存储参数可将其挂载进容器# Set the path to your custom config.yaml file CUSTOM_RUN_CONFIG/path/to/your/custom-config.yaml OGX_PORT8321 docker run \ -it \ --pull always \ -p $OGX_PORT:$OGX_PORT \ -v ~/.ogx:/root/.ogx \ -v $CUSTOM_RUN_CONFIG:/app/custom-config.yaml \ -e RUN_CONFIG_PATH/app/custom-config.yaml \ -e NVIDIA_API_KEY$NVIDIA_API_KEY \ ogxai/distribution-nvidia \ --port $OGX_PORT注意运行配置必须先挂载进容器才能被使用。-v标志将本地文件挂载到容器内路径RUN_CONFIG_PATH环境变量则告诉入口脚本使用哪份配置。该分发当前提供的可用运行配置为config.yaml即分发自带的默认配置对应 src/ogx/distributions/nvidia/config.yaml。方式三venv本地源码运行如果你已搭建好本地开发环境也可以通过本地虚拟环境安装分发依赖并直接运行INFERENCE_MODELmeta-llama/Llama-3.1-8B-Instruct ogx stack list-deps nvidia | xargs -L1 uv pip install NVIDIA_API_KEY$NVIDIA_API_KEY \ INFERENCE_MODEL$INFERENCE_MODEL \ ogx stack run ./config.yaml \ --port 8321其中ogx stack list-deps nvidia会列出该分发所需的全部依赖包配合uv pip install逐行安装ogx stack run则按配置启动服务。此处可替换INFERENCE_MODEL为你希望注册的模型 ID例如示例中的meta-llama/Llama-3.1-8B-Instruct。源码视角推理适配器的鉴权与模型清单理解 NVIDIA Distribution 的运行机制关键在NVIDIAInferenceAdaptersrc/ogx/providers/remote/inference/nvidia/nvidia.py。其get_api_key方法体现了两种模式的鉴权差异若配置了auth_credential优先使用配置中的密钥若为自托管模式非托管端点返回NO KEY REQUIRED即自托管 NIM 无需 API Key托管模式下缺失密钥时返回None并在初始化阶段记录错误日志。list_provider_model_ids会动态拉取 NVIDIA 端点上的模型列表并将其与rerank_model_to_url中静态配置的 rerank 模型 ID 去重合并后返回即使动态拉取失败例如 API Key 失效也会降级为仅返回已配置的 rerank 模型同时记录警告避免“静默空列表”掩盖配置错误。示例 Notebooks如需完整的端到端示例使用 NVIDIA Distribution 运行推理与评测负载可参考仓库中 docs/notebooks/nvidia 目录下的示例 Notebook包括beginner_e2e初阶端到端与tool_calling工具调用两组示例均以.ipynb/.py形式提供可直接在本地或云端环境运行。小结NVIDIA Distribution 是 OGX 生态中面向 NVIDIA 推理栈的“一键装配”方案推理走 NVIDIA NIM托管或自托管文件与向量检索由本地 FAISS/Localfs 承担评测与数据集通过 NeMo Evaluator 与 Data Store 接入全部接线由一份config.yaml与若干环境变量完成。从配置结构、NIM 部署到三种启动方式本文覆盖了将 OGX 与 NVIDIA 服务集成跑通所需的全部关键步骤结合 src/ogx/providers/remote/inference/nvidia/ 的适配器源码你也可以进一步按需定制 base_url、rerank 端点或嵌入模型元数据。【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
