ogx_client Python SDK 完整参考OGX 全部 API 资源的方法、类型与实战用法【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx本篇文章是 OGXOpen GenAI Stack官方 Python SDKogx_client的全量 API 参考指南覆盖工具组Toolgroups、推理Inference、评测Eval、向量存储Vector Stores/VectorDBs、模型管理、数据集、评分函数等全部资源模块的类型与调用方法。读完本文你将能独立完成客户端初始化、资源注册/查询、Agent 会话编排、RAG 检索与评测任务提交并理解 SDK 从types命名空间迁移到models命名空间的版本差异。一、SDK 概况与版本基础ogx_client是 OGX 的官方 Python 客户端提供同步客户端OgxClient与异步客户端AsyncOgxClient与 OGX 服务器默认端口 8321通过 HTTP 通信。从 SDK 1.1.4 起其底层代码生成后端由外部商业服务切换为开源的 OpenAPI Generator但包名与调用方式保持不变具体背景见博客 The OGX Python SDK Has a New Foundation。版本与依赖要求依据迁移指南 Migrating to ogx_client 1.1.4: The Complete Reference1.1.4 之后的环境要求如下依赖要求Python 3.12pydantic 2httpx 0.28.1同步与异步均基于 httpxaiohttp后端已移除typing-extensions 4.7.1python-dateutil 2.8.2重要types已更名为models本参考文档docs/docs/references/python_sdk_reference/index.md中出现的from ogx_client.types import ...属于 1.1.3 及之前的写法。在 1.1.4 及之后类型统一收敛到扁平化的ogx_client.models命名空间# 1.1.3 及之前旧 from ogx_client.types import ResponseObject from ogx_client.types.shared import HealthInfo # 1.1.4 及之后新——所有模型从单一命名空间导入 from ogx_client.models import OpenAIResponseObject, HealthInfo类型命名也发生系统性调整包装 OpenAI 兼容对象的类型加OpenAI前缀资源类型加Object后缀例如ResponseObject→OpenAIResponseObject、VectorStore→VectorStoreObject、File→OpenAIFileObject。下文各小节会同时标注新旧名称方便对照迁移。二、客户端初始化与连接配置与服务器交互的第一步是创建客户端。以下用法在 1.1.4 前后均有效参考 USAGE_EXAMPLES.mdfrom ogx_client import OgxClient # 连接本地 OGX 服务器 client OgxClient(base_urlhttp://localhost:8321) # 带 API Key设置 Authorization: Bearer key 请求头 client OgxClient(base_urlhttp://localhost:8321, api_keyyour-api-key) # 1.1.4 新增configuration 参数字符串或 Configuration 对象 from ogx_client import Configuration config Configuration(hosthttp://localhost:8321, timeout30, retries3) client OgxClient(configurationconfig)客户端同时支持环境变量配置构造函数参数优先于环境变量环境变量行为OGX_CLIENT_BASE_URL自动作为base_urlOGX_CLIENT_API_KEY设置Authorization: Bearer key头OGX_CLIENT_CUSTOM_HEADERS解析并合并进默认请求头上下文管理器会自动释放底层连接资源with OgxClient(base_urlhttp://localhost:8321) as client: response client.responses.create(modelllama-3.3-70b, inputHello)三、Shared Types跨模块共享的数据类型所有资源模块共用一组基础类型旧ogx_client.types写法新版本从ogx_client.models导入同名类型from ogx_client.types import ( AgentConfig, # Agent 配置模型、指令、工具等 BatchCompletion, # 批量完成结果 CompletionMessage, # 完成消息 ContentDelta, # 流式内容增量 Document, # 文档 InterleavedContent, # 交错内容多模态 InterleavedContentItem, Message, # 通用消息 ParamType, # 参数类型 QueryConfig, # 查询配置 QueryResult, # 查询结果 ReturnType, # 返回类型 SamplingParams, # 采样参数temperature、top_p 等 ScoringResult, # 评分结果 SystemMessage, # 系统消息 ToolCall, # 工具调用 ToolParamDefinition, # 工具参数定义 ToolResponseMessage, # 工具响应消息 URL, # 统一资源定位 UserMessage, # 用户消息 )其中SamplingParams是推理与评测中反复出现的核心类型对应采样策略greedy 等、temperature、top_p、repeat_penalty、max_tokens等生成参数ParamType/ReturnType则用于定义评分函数的参数与返回值结构见下文 ScoringFunctions 小节。这些类型在评测配置中同样出现例如benchmarking/rag/benchmarks/base.py所定义的评测基类即以SamplingParams驱动模型生成。四、Toolgroups工具组管理工具组Toolgroup是多个工具的集合例如内置的文件检索builtin::file_search、网页搜索builtin::websearch等。类型from ogx_client.types import ( ListToolGroupsResponse, ToolGroup, ToolgroupListResponse, )方法client.toolgroups.list() - ToolgroupListResponse— 列出全部工具组GET/v1/toolgroupsclient.toolgroups.get(toolgroup_id) - ToolGroup— 按 ID 获取工具组详情GET/v1/toolgroups/{toolgroup_id}client.toolgroups.register(**params) - None— 注册新工具组POST/v1/toolgroups参数通常包含provider_id、provider_toolgroup_id、mcp_configMCP 端点 JSON 配置与argsclient.toolgroups.unregister(toolgroup_id) - None— 注销工具组DELETE/v1/toolgroups/{toolgroup_id}工具组列表可通过命令行ogx-client toolgroups list快速查看见 OGX Client CLI 参考输出示例包括builtin::file_search与builtin::websearch两个内置工具组。五、Tools 与 ToolRuntime工具查询与运行时调用Tools只读查询from ogx_client.types import ListToolsResponse, Tool, ToolListResponseclient.tools.list(**params) - ToolListResponse— 列出工具GET/v1/toolsclient.tools.get(tool_name) - Tool— 获取单个工具GET/v1/tools/{tool_name}ToolRuntime实际执行工具from ogx_client.types import ToolDef, ToolInvocationResultclient.tool_runtime.invoke_tool(**params) - ToolInvocationResult— 调用工具POST/v1/tool-runtime/invokeclient.tool_runtime.list_tools(**params) - JSONLDecoder[ToolDef]— 以 JSONL 流式解码方式列出可用工具GET/v1/tool-runtime/list-tools返回流式解码器以应对大数量工具工具运行时在 OGX 中对应src/ogx/core的运行时服务层与 工具使用文档负责将模型输出的ToolCall解析为真实的工具执行。RagTool内置 RAG 工具client.tool_runtime.rag_tool.insert(**params) - None client.tool_runtime.rag_tool.query(**params) - QueryResultrag_tool.insertPOST/v1/tool-runtime/rag-tool/insert— 向 RAG 工具插入文档rag_tool.queryPOST/v1/tool-runtime/rag-tool/query— 检索并返回QueryResult这是 OGX 在工具运行时层内置的检索增强生成入口配合向量存储可实现检索 → 注入上下文 → 生成的完整链路可参考 RAG 构建文档 与 RAG 生命周期示例。六、Agents会话式智能体已弃用弃用警告Agents API 已弃用官方建议改用 OpenAI 兼容的 Responses APIclient.responses.create()新应用请参考 Responses vs Agents。from ogx_client.types import ( InferenceStep, MemoryRetrievalStep, ToolExecutionStep, ToolResponse, AgentCreateResponse, )方法client.agents.create(**params) - AgentCreateResponse— 创建 AgentPOST/v1/agentsclient.agents.delete(agent_id) - None— 删除 AgentDELETE/v1/agents/{agent_id}Agent 的生命周期围绕 会话Session→ 轮次Turn→ 步骤Step三层结构展开Session 会话from ogx_client.types.agents import Session, SessionCreateResponseclient.agents.session.create(agent_id, **params) - SessionCreateResponseclient.agents.session.retrieve(session_id, *, agent_id, **params) - Sessionclient.agents.session.delete(session_id, *, agent_id) - NoneTurn 轮次from ogx_client.types.agents import Turn, TurnCreateResponseclient.agents.turn.create(session_id, *, agent_id, **params) - TurnCreateResponseclient.agents.turn.retrieve(turn_id, *, agent_id, session_id) - TurnSteps 步骤from ogx_client.types.agents import StepRetrieveResponseclient.agents.steps.retrieve(step_id, *, agent_id, session_id, turn_id) - StepRetrieveResponse步骤类型InferenceStep推理步骤、ToolExecutionStep工具执行步骤、MemoryRetrievalStep记忆检索步骤分别对应 Agent 执行循环中的不同阶段可用 Agent 执行循环文档 与 Agent 工作流示例 深入理解其运行机制。七、Datasets数据集注册与管理from ogx_client.types import ( ListDatasetsResponse, DatasetRetrieveResponse, DatasetListResponse, )方法client.datasets.retrieve(dataset_id) - Optional[DatasetRetrieveResponse]— 查询单个数据集GET/v1/datasets/{dataset_id}client.datasets.list() - DatasetListResponse— 列出数据集GET/v1/datasetsclient.datasets.register(**params) - None— 注册数据集POST/v1/datasets常见参数为dataset_id、purpose、url或本地dataset_path、metadataclient.datasets.unregister(dataset_id) - None— 注销数据集DELETE/v1/datasets/{dataset_id}数据集是评测Eval与评分Scoring的数据来源。命令行等价操作见 OGX Client CLI 参考 的datasets命令组。八、Eval评测任务与作业管理from ogx_client.types import EvaluateResponse, Job方法client.eval.evaluate_rows(benchmark_id, **params) - EvaluateResponse— 同步评估数据行POST/v1/eval/tasks/{benchmark_id}/evaluationsclient.eval.run_eval(benchmark_id, **params) - Job— 提交异步评测作业POST/v1/eval/tasks/{benchmark_id}/jobsJobs 作业子资源from ogx_client.types.eval import JobStatusResponseclient.eval.jobs.retrieve(job_id, *, benchmark_id) - EvaluateResponse— 获取评测结果GET/v1/eval/tasks/{benchmark_id}/jobs/{job_id}/resultclient.eval.jobs.status(job_id, *, benchmark_id) - Optional[JobStatusResponse]— 查询作业状态GET/v1/eval/tasks/{benchmark_id}/jobs/{job_id}client.eval.jobs.cancel(job_id, *, benchmark_id) - None— 取消作业DELETE/v1/eval/tasks/{benchmark_id}/jobs/{job_id}典型的评测流程为先run_eval提交作业获得Job再轮询jobs.status完成后用jobs.retrieve取回EvaluateResponse。OGX 的评测后端对应 核心作业模块 与 评测构建文档仓库内还提供了 Evals 参考 与完整的 RAG 评测基准 作为实战范例。九、Inspect 与 Inference服务器探活与嵌入推理Inspect健康与版本from ogx_client.types import HealthInfo, ProviderInfo, RouteInfo, VersionInfoclient.inspect.health() - HealthInfo— 服务器健康检查GET/v1/healthclient.inspect.version() - VersionInfo— 服务器版本信息GET/v1/version这两个接口对应 inspect API 模块可用于部署后的连通性自检。Inference嵌入向量from ogx_client.types import ( CompletionResponse, EmbeddingsResponse, TokenLogProbs, InferenceChatCompletionResponse, InferenceCompletionResponse, )client.inference.embeddings(**params) - EmbeddingsResponse— 生成文本嵌入POST/v1/inference/embeddings参数包含model或model_id与input文本聊天/补全推理能力建议直接使用 OpenAI 兼容的client.chat.completions.create()或 Responses API底层由 inference API 模块 与各远程推理 provider 实现。十、VectorIo 与 VectorDBs向量检索已弃用弃用警告两个向量相关 API 均已被 OpenAI 兼容的 Vector Stores API 取代将在未来版本移除见 Issue #2981。VectorIo原向量读写from ogx_client.types import QueryChunksResponseclient.vector_io.insert(**params) - None— 插入向量块POST/v1/vector-io/insertclient.vector_io.query(**params) - QueryChunksResponse— 查询向量块POST/v1/vector-io/queryVectorDBs原向量库管理from ogx_client.types import ( ListVectorDBsResponse, VectorDBRetrieveResponse, VectorDBListResponse, VectorDBRegisterResponse, )client.vector_dbs.retrieve(vector_db_id) - Optional[VectorDBRetrieveResponse]client.vector_dbs.list() - VectorDBListResponseclient.vector_dbs.register(**params) - VectorDBRegisterResponseclient.vector_dbs.unregister(vector_db_id) - None迁移到 Vector Stores API旧 API已弃用新 Vector Stores APIclient.vector_io.insert()client.vector_stores.files.create()client.vector_stores.files.chunks.create()client.vector_io.query()client.vector_stores.search()client.vector_dbs.register()client.vector_stores.create()client.vector_dbs.list()client.vector_stores.list()client.vector_dbs.retrieve()client.vector_stores.retrieve()client.vector_dbs.unregister()client.vector_stores.delete()新 API 的完整用法参见 RAG 迁移文档 与 文件与向量存储概念。旧实现的源码位于 vector_io API 模块底层对接各向量数据库 providervector_io providers。十一、Models模型注册与管理from ogx_client.types import ListModelsResponse, Model, ModelListResponse方法client.models.retrieve(model_id) - Optional[Model]— 查询模型GET/v1/models/{model_id}client.models.list() - ModelListResponse— 列出模型GET/v1/modelsclient.models.register(**params) - Model— 注册模型POST/v1/models参数包含model_id、provider_id、provider_model_id、model_typellm/embedding、metadataclient.models.unregister(model_id) - None— 注销模型DELETE/v1/models/{model_id}对应 models API 模块。命令行示例见 OGX Client CLI 参考ogx-client models list展示模型表model_type / identifier / provider_resource_id / provider_idogx-client models register model_id --provider-id provider_id完成注册。十二、PostTraining 与 SyntheticDataGeneration当前不可用 API不可用警告OGX 当前没有 provider 实现这两个 APISDK 类型仅为前向兼容保留端点处于非功能状态。PostTrainingfrom ogx_client.types import ListPostTrainingJobsResponse, PostTrainingJobclient.post_training.preference_optimize(**params) - PostTrainingJobclient.post_training.supervised_fine_tune(**params) - PostTrainingJob子资源 Jobfrom ogx_client.types.post_training import JobListResponse, JobArtifactsResponse, JobStatusResponseclient.post_training.job.list() - JobListResponseclient.post_training.job.artifacts(**params) - Optional[JobArtifactsResponse]client.post_training.job.cancel(**params) - Noneclient.post_training.job.status(**params) - Optional[JobStatusResponse]SyntheticDataGenerationfrom ogx_client.types import SyntheticDataGenerationResponseclient.synthetic_data_generation.generate(**params) - SyntheticDataGenerationResponsePOST/v1/synthetic-data-generation/generate集成时请通过client.inspect.version()与client.providers.list()确认运行环境实际支持的能力范围。十三、Providers 与 Routes运行环境观测from ogx_client.types import ListProvidersResponse, ProviderListResponse from ogx_client.types import ListRoutesResponse, RouteListResponseclient.providers.list() - ProviderListResponse— 列出已注册的 API providerGET/v1/inspect/providersclient.routes.list() - RouteListResponse— 列出服务器路由GET/v1/inspect/routesProviderInfo与RouteInfo属于共享类型旧types.shared新ogx_client.models。命令行ogx-client providers list会以表格展示各 APIinference/scoring/agents/memory 等对应的 provider 与类型builtin或remote::vllm等。十四、Datasetio数据集行级读写from ogx_client.types import PaginatedRowsResultclient.datasetio.append_rows(**params) - None— 追加数据行POST/v1/datasetio/rowsclient.datasetio.get_rows_paginated(**params) - PaginatedRowsResult— 分页读取数据行GET/v1/datasetio/rows该接口用于评测数据集的行级增量写入与读取配合 Eval 与 Scoring 完成数据闭环。十五、Scoring 与 ScoringFunctions评分执行与评分函数管理Scoring执行评分from ogx_client.types import ScoringScoreResponse, ScoringScoreBatchResponseclient.scoring.score(**params) - ScoringScoreResponse— 单条评分POST/v1/scoring/scoreclient.scoring.score_batch(**params) - ScoringScoreBatchResponse— 批量评分POST/v1/scoring/score-batchScoringFunctions评分函数注册from ogx_client.types import ( ListScoringFunctionsResponse, ScoringFn, ScoringFunctionListResponse, )client.scoring_functions.retrieve(scoring_fn_id) - Optional[ScoringFn]— 查询GET/v1/scoring-functions/{scoring_fn_id}client.scoring_functions.list() - ScoringFunctionListResponse— 列出GET/v1/scoring-functionsclient.scoring_functions.register(**params) - None— 注册POST/v1/scoring-functions参数包含scoring_fn_id、description、return_type、provider_id、params内置评分函数示例ogx-client scoring_functions list输出basic::equality输入等于目标返回 1.0否则 0.0、basic::docvqa视觉问答评分。OGX 也提供完整评测框架见 Evals 参考。十六、Benchmarks评测基准管理from ogx_client.types import ( Benchmark, ListBenchmarksResponse, BenchmarkListResponse, )client.benchmarks.retrieve(benchmark_id) - Optional[Benchmark]— 查询基准GET/v1/eval-tasks/{benchmark_id}client.benchmarks.list() - BenchmarkListResponse— 列出基准GET/v1/eval-tasksclient.benchmarks.register(**params) - None— 注册基准POST/v1/eval-tasks仓库内置了可直接运行的评测基准实现例如 RAG 评测BEIR / Doc2Dial / MultiHop / QRECC评测结果汇总见 RAG 评测报告。十七、错误处理、流式与异步错误处理SDK 异常类名保持稳定BadRequestError、NotFoundError、RateLimitError等。1.1.4 后属性发生变化from ogx_client import NotFoundError try: client.models.retrieve(non-existent) except NotFoundError as e: print(e.status) # 旧版为 e.status_code新版两者皆可 print(e.body) # 原始响应体字符串 print(e.headers) # 响应头流式输出stream client.responses.create(modelllama-3.3-70b, inputHello, streamTrue) for event in stream: print(event)异步客户端from ogx_client import AsyncOgxClient async def main(): client AsyncOgxClient(base_urlhttp://localhost:8321) response await client.responses.create(modelllama-3.3-70b, inputHello) print(response.output) asyncio.run(main())十八、进一步阅读Python SDK 迁移指南1.1.4 完整对照表SDK 新基础公告博客SDK 用法示例OpenAPI 客户端OGX Client CLI 参考SDK 生成模板与策略快速入门 与 详细教程【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考