企业官网建设流程全解析

OGX 的 Responses API：用开源栈构建自有规则的多工具 Agent

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

导读

本文围绕 OGX（Open GenAI Stack）对 OpenAI Responses API 的实现展开，覆盖服务端编排的核心原理、file_search私有 RAG、基于 MCP 的多工具协调、OpenAI 客户端生态兼容，以及 Open Responses 开放标准带来的演进方向。读完本文，你将掌握如何在本地或自有基础设施上，用一条 API 调用搭建具备检索增强与多工具编排能力的 Agent，并能对照源码理解参数背后的实现机制。

为什么需要 Responses API：把编排从客户端搬到服务端

在 Responses API 出现之前，构建一个能使用工具的 Agent 是一个发生在客户端的多步编排流程：应用程序需要先把可用工具列表发给模型，检查返回结果中是否有工具调用请求，执行这些工具，把结果回传模型，然后不断重复，直到模型产出最终答案。所有状态管理、错误处理和重试逻辑都堆在应用代码里。

这种模式给应用开发者带来沉重负担——编排逻辑在每个应用里被反复复制，状态管理上的细微错误会导致回答准确率下降，或者触发不必要的模型调用。

Responses API 的核心变化是把编排移到服务端：客户端只需发送问题，同时附上一组可用工具和文档，服务端在内部完成规划（planning）、工具执行（tool execution）与结果综合（synthesis）。客户端代码因此大幅简化，行为也更一致，因为编排逻辑被共享而非被每个应用重复实现。

在 OGX 中，这一能力由 src/ogx_api/responses 模块承载。其中 api.py 定义了Responses协议，包含create_openai_response、get_openai_response、list_openai_responses、list_openai_response_input_items、delete_openai_response、compact_openai_response、cancel_openai_response等核心方法；fastapi_routes.py 则把这些能力暴露为 REST 路由。

OGX 暴露的 Responses 端点

从 fastapi_routes.py 的路由定义可以看到，OGX 在/v1前缀下提供了完整的 Responses 端点族：

其中POST /v1/responses对stream=true的请求会返回text/event-stream的流式响应；/responses/compact用于把超长会话压缩成更小的表示同时保留上下文，对长对话场景很重要。

OGX 在 API 表面之外提供了什么

OGX 是一个开源 AI 应用服务端，为推理、RAG、工具调用、安全、评测等提供统一 API，并通过可插拔的 Provider 架构让你更换组件而无需改动应用代码。OGX 的 Responses API 实现支持内置 RAG（file_search）、基于 MCP 的自动化多工具编排、会话状态管理，以及与 OpenAI 客户端生态的兼容。

而真正有意思的是 API 表面之外的三点价值：

模型自由

在闭源托管服务中，Responses API 与单一厂商的一组模型绑定。而 OGX 可以使用其推理 Provider 能够访问到的任何模型：Llama 家族等开源模型、你自己微调的模型，或生态中其他优化模型。同一个 Responses API 接口不依赖具体模型。开发阶段用小模型、生产阶段换大模型、或者整体更换模型供应商，应用代码都不用改。

数据主权

在金融、医疗、政府等受监管行业，把敏感文档发送给第三方云服务往往不可行。OGX 允许你在自己的基础设施上运行整个技术栈：模型、RAG 用的向量库、工具执行环境。文档不离开你的安全边界，Agent 对这些文档的推理过程同样留在边界内。

开放、可扩展的架构

OGX 的 Provider 架构意味着任何组件都不会被锁死在单一实现上。开发环境用 FAISS 做向量库、生产环境换 Milvus？改一处配置即可。本地用 Ollama、生产用云端推理 Provider？同一份应用代码，不同 distribution 而已。这种灵活性覆盖整个 OGX API 表面，而不仅仅是推理。

私有 RAG：file_search工具

检索增强生成（RAG）把模型的回答锚定在权威文档上，从而减少幻觉，并让私有知识库也能产出准确答案。

Responses API 用file_search工具把 RAG 形式化：你先创建向量库（vector store）、上传文档，然后在调用 Responses API 时把file_search作为可用工具传入。模型会生成搜索查询、检索相关段落并综合成有依据的回答——所有这些都在一次 API 调用内完成。

在 OGX 中，这条流水线全程运行在你自己的基础设施上：文档摄取、向量化嵌入、存储、检索、综合都在本地完成。响应中还会携带来源段落引用，应用可以据此提供可核验的引用。

配置file_search

file_search依赖 OGX 的 tool_runtime Provider。根据 tools.mdx 的说明，在 stack 配置的tool_runtime中配置inline::file-searchProvider 后，builtin::file_search工具组就会被自动注册。例如 k8s 部署配置 中的写法：

tool_runtime: - provider_id: file-search provider_type: inline::file-search

用 Responses API 做一次 RAG 查询

结合 RAG 指南 中的示例，完整流程如下（假设 OGX 服务已运行在localhost:8321）：

import io, requests from openai import OpenAI url = "https://www.paulgraham.com/greatwork.html" client = OpenAI(base_url="http://localhost:8321/v1/", api_key="none") # 1. 创建向量库 vs = client.vector_stores.create() # 2. 上传文档并挂到向量库 response = requests.get(url) pseudo_file = io.BytesIO(str(response.content).encode('utf-8')) file_id = client.files.create( file=(url, pseudo_file, "text/html"), purpose="assistants" ).id client.vector_stores.files.create(vector_store_id=vs.id, file_id=file_id) # 3. 通过 Responses API 自动完成检索与回答 resp = client.responses.create( model="gpt-4o", input="How do you do great work?", tools=[{"type": "file_search", "vector_store_ids": [vs.id]}], include=["file_search_call.results"], ) print(resp.output[-1].content[-1].text)

关键点在于include=["file_search_call.results"]：它要求响应携带文件搜索调用结果，便于应用侧展示引用来源。从源码看，file_search_call.results是 openai_responses.py 中定义的内容类型之一，对应file_search_call.results条目；工具类型本身定义在 openai_responses.py（type恒为"file_search"），其调用则表现为file_search_call类型的输出条目。

测试用例印证

仓库的集成测试 test_cases.py 给出了file_search的端到端用例：例如向模型提问 "How many experts does the Llama 4 Maverick model have?"，配合tools=[{"type": "file_search"}]与文档内容，期望模型基于检索结果回答 "128"。测试还覆盖了 PDF 文档场景（file_path="pdfs/ogx_and_models.pdf"）。这些用例证明：file_search不仅支持文本文件，也能处理 PDF 等经 Files API 处理的文档类型。

多工具编排：连接 MCP 服务器

当一个 Agent 需要协调多个工具回答复杂问题时，Responses API 的价值更加凸显。以"罗德岛有哪些公园？它们近期有没有活动？"这类问题为例，回答它需要：发现可用工具、搜索公园、逐个查询公园的活动、综合所有结果。在 OGX 的 Responses API + MCP 集成下，这一整套流程发生在单次 API 调用内：模型从连接的 MCP 服务器发现工具、规划并执行一串工具调用、产出综合答案，客户端不需要编写任何编排逻辑。

MCP 是开放的工具集成标准，可用工具生态广阔且持续增长。任何 MCP 服务器——无论连接数据库、内部服务还是外部数据源——都可以接入 OGX 并被 Responses API 使用。

注册 MCP 服务器

根据 tools.mdx 的说明，推荐的方式是在 stack 配置中用 connectors 注册：

connectors: - connector_id: "mcp::deepwiki" connector_type: mcp url: "https://mcp.deepwiki.com/sse"

然后在调用时通过connector_id引用：

agent = Agent( client, model="meta-llama/Llama-3.2-3B-Instruct", instructions="You are a helpful assistant.", tools=[ { "type": "mcp", "connector_id": "mcp::deepwiki", "server_label": "deepwiki", } ], ) agent.create_turn(...)

不少 MCP 服务器需要认证（常见为 OAuth2.0），可以在工具定义里携带令牌：

tools=[ { "type": "mcp", "connector_id": "mcp::deepwiki", "server_label": "deepwiki", "authorization": "<your_access_token>", # OAuth token（不要带 "Bearer " 前缀） } ]

也可以不注册 connector，直接把server_url传给工具定义：

tools=[ { "type": "mcp", "server_url": "https://mcp.deepwiki.com/sse", "server_label": "deepwiki", } ]

自有 MCP 服务器示例

先用supergateway把一个文件系统 MCP 服务器暴露为 SSE 端点：

mkdir /tmp/content touch /tmp/content/foo touch /tmp/content/bar npx -y supergateway --port 8000 --stdio 'npx -y @modelcontextprotocol/server-filesystem /tmp/content'

再注册为 connector 并引用即可，方法与远程服务器一致（详见 tools.mdx）：

connectors: - connector_id: "mcp::filesystem" connector_type: mcp url: "http://localhost:8000/sse"

agent = Agent( client, model="meta-llama/Llama-3.2-3B-Instruct", instructions="You are a helpful file system assistant.", tools=[ { "type": "mcp", "connector_id": "mcp::filesystem", "server_label": "filesystem", } ], )

集成测试同样覆盖了 MCP 场景：test_cases.py 中的mcp_tool_test_cases通过{"type": "mcp", "server_label": "localmcp", "server_url": ...}验证模型调用 MCP 工具的能力，测试运行器会把占位符<FILLED_BY_TEST_RUNNER>替换为真实服务器地址。

细粒度的工具访问控制

OGX 对工具访问提供细粒度控制：你可以限制某次请求可用的工具集合、向 MCP 服务器透传每请求的认证头（让 Agent 只能访问当前用户的数据）、在不改动 Agent prompt 的前提下配置工具行为。这在生产环境的安全与访问控制场景中非常关键。

从 models.py 可以看到相关请求参数：tool_choice控制模型如何选择工具（OpenAIResponseInputToolChoice），max_infer_iters（默认 10，最小 1）限定推理迭代的最大次数，防止多工具循环无限执行；max_tool_calls则限定单条响应中内置工具调用总数。这些参数共同构成了生产环境下防止失控循环的安全阀。

框架兼容：指向你的 OGX 服务器即可

OGX 在/v1暴露 OpenAI 兼容端点，因此官方 OpenAI Python 客户端、OGX 客户端，以及任何会说 OpenAI API 的客户端都可以直接用，行为一致。迁移已有基于 OpenAI 客户端写的代码，只需把客户端指向你的 OGX 服务器——仅此而已。这也适用于 LangChain 等构建在 OpenAI API 之上的框架：切换推理后端只需改一个构造参数，无需重写 Agent 逻辑。

这种即插即用兼容性的实际意义不止于方便：你可以在本地 OGX 服务器上开发测试，在生产用 OGX distribution 部署，或在不同 OpenAI 兼容 Provider 之间切换，应用代码完全不变。

核心请求参数速查

CreateResponseRequest 定义了 OGX Responses 请求的完整参数面，以下是常用参数：

其中previous_response_id与store组合实现了会话延续：store=true（默认）时响应持久化到数据库，后续请求可用previous_response_id续写；流式模式下，fastapi_routes.py 的 WebSocket 端点还会维护连接级缓存，允许在同一个 socket 上通过previous_response_id延续一条从未持久化的响应链。

一次请求的内部流转

从 Responses 内部流转文档 可以看到，一条 Responses 请求会在内部编排推理、工具执行、guardrails 检查与状态持久化。核心是推理循环（inference loop）：模型调用工具 → 拿到结果 → 再次调用推理，直到不再产生服务端工具调用、返回客户端function_call、或达到max_infer_iters上限。流式场景下，服务端通过 SSE 事件（如response.reasoning_text.delta、response.file_search_call.in_progress、response.mcp_call.completed等，定义见 openai_responses.py）把进展实时推给客户端。

走向开放标准：Open Responses

OGX 最初实现 Responses API 时，该规范还是私有的。OGX 必须追赶一个移动的目标，OpenAI 每次新增功能到 OGX 实现之间总存在时间差。

Open Responses 规范改变了这一点。它是由包括 OpenAI、Hugging Face 以及 Ollama、vLLM、LM Studio 等提供商在内的广泛社区支持的开放规范，把 Responses API 的核心概念形式化为开放标准：以 item 作为上下文的原子单元、语义化的流式事件，以及"推理 + 工具调用"的 Agent 循环。

对 OGX 而言，Open Responses 提供了一个稳定、社区治理的规范来构建，而非私有的移动目标。这也意味着 OGX 的 Responses API 实现属于更广泛的可互操作 Provider 生态：基于 Open Responses 规范构建的应用，可以在 OGX、OpenAI、Hugging Face 基础设施或 Ollama 等本地 Provider 上运行，无需修改代码。

该规范还引入了一些对生产部署至关重要的概念：

• 推理可见性（Reasoning visibility）：规范明确了模型如何暴露推理过程，支持审计追踪与治理工作流。OGX 的响应对象中对应reasoning输出条目与reasoning_text内容类型，流式事件包括response.reasoning_text.delta、response.reasoning_summary_part.added等（见 openai_responses.py）。
• 内部工具 vs 外部工具：清晰区分在 Provider 基础设施内执行（如file_search）与由客户端执行的工具，让开发者确切知道计算发生在哪里。在 OGX 的响应对象中，file_search_call（内部工具调用）与function_call（客户端工具调用）是不同类型的输出条目。
• 不碎片化的可扩展性：Provider 可以在保持稳定、可互操作核心的同时增加自定义能力。

对于 OGX 社区，投资 Responses API 不只是为了兼容某一家厂商，而是构建在一个行业正在趋同的开放标准之上。

快速上手

如果你刚接触 OGX，按以下步骤即可起一个本地服务（需要先安装 uv）：

ollama pull llama3.2:3b uvx ogx go

启动后，OGX 服务默认监听localhost:8321，OpenAI 兼容端点位于http://localhost:8321/v1/。更多入门内容可参考 Getting Started 快速上手 与 详细教程；Responses API 与 Agents API 的选型对比见 Responses vs Agents；关于file_search、MCP 的完整配置与工具管理，可继续阅读 RAG 指南 与 Tools 指南。

Responses API 仍在快速演进，无论 OGX 还是 Open Responses 规范都是如此。如果你正在构建真实应用，不妨对照 Responses 集成测试 中的file_search_test_cases与mcp_tool_test_cases，验证你的场景并分享经验——这对规范与实现的共同完善很有价值。

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