使用开源智能体 API 服务器 OGX 构建 AI 应用
内容提要
OGX 是 Meta Llama Stack 更名后的开源智能体 API 服务器，兼容 OpenAI 接口，支持任意模型与基础设施。文章介绍如何用 OGX 和 Ollama 构建 DocBrain 应用：上传文档实现自动 RAG 检索，并通过自定义工具将文档中的待办事项保存到本地文件。核心优势是本地开发与生产部署可无缝切换，无需重写应用。
延伸解读
OGX 与 Llama Stack 的关系
文章明确指出 OGX 是 Meta Llama Stack 更名后的项目，其 GitHub 页面直接说明“Llama Stack is now OGX”。更名伴随着使命转变：从特定模型转向模型无关、多 SDK 和生产级。这意味着许多关于 Llama Stack 的现有资料仍适用于 OGX，但需注意其定位已扩展为通用智能体 API 服务器，而非仅限 Llama 模型。
本地开发到生产部署的无缝切换
OGX 的可插拔提供者架构允许在本地使用 Ollama 开发，之后切换到 vLLM 或云服务时，只需更改模型字符串和提供者配置，应用代码无需重写。文章强调，向量存储逻辑、自定义工具和调度循环都保持不变。这种设计降低了从原型到生产的迁移成本，但实际切换时仍需确保目标后端支持所需功能。
内置 RAG 与自定义工具的协同
OGX 的 Responses API 将文件搜索（RAG）和自定义工具调用整合到同一个 tools 列表中，模型可同时推理两者。文章示例中，DocBrain 既能基于上传文档回答问题，又能通过 save_action_item 工具将待办事项保存到本地 JSONL 文件。这种设计避免了手动拼接检索与工具系统，但需注意工具描述应具体，以防模型过度触发。
本地开发的安全与配置细节
文章提到 OGX 默认使用 HTTPS 并自带自签名证书，本地测试时需跳过证书验证（如 curl 的 -k 或 httpx 的 verify=False）。API 密钥在本地服务器中不被检查，任意字符串即可。这些细节简化了本地起步，但若部署到生产环境，应替换为正式证书和认证机制，不可直接沿用本地配置。
Q&A
OGX 和 Meta 的 Llama Stack 是什么关系？
OGX 是 Meta Llama Stack 更名后的项目，其 GitHub 页面明确说明 Llama Stack 现在就是 OGX。更名伴随着使命的真正转变：OGX 致力于成为模型无关、多 SDK、生产级的开源智能体 API 服务器，而不是一个架构相似的新项目。
OGX 的核心特点是什么？
OGX 是一个开源的智能体 API 服务器，兼容 OpenAI 接口，支持任意模型和基础设施。它采用可插拔的提供者架构，可以在本地用 Ollama 开发，生产环境切换到 vLLM 或云服务，而无需重写应用。它还支持 Responses API 进行服务端智能体编排、工具调用、MCP 服务器集成和内置的 RAG 文件搜索，并原生支持 OpenAI、Anthropic 和 Google GenAI SDK。
如何安装和启动 OGX 服务器？
首先安装 uv 和 Ollama，并拉取模型（如 ollama pull llama3.2:3b）。然后创建项目：uv init docbrain && cd docbrain，再安装依赖：uv add ogx openai。启动服务器使用 uv run ogx go，默认监听 https://localhost:8321。可以用 curl -k -s https://localhost:8321/v1/models 验证服务器是否健康。
如何在 OGX 中实现 RAG 检索？
使用 OGX 内置的文件搜索功能。先上传文档：client.files.create(file=open('lease_agreement.pdf', 'rb'), purpose='assistants')，然后创建向量存储并索引文件：client.vector_stores.create(name='docbrain-kb', file_ids=[file.id])。提问时在 tools 参数中加入 {'type': 'file_search', 'vector_store_ids': [vector_store.id]}，OGX 会自动进行分块、嵌入和检索，并基于文档内容生成回答。
如何为 OGX 添加自定义工具来保存待办事项？
定义一个 Python 函数（如 save_action_item），它接收描述、来源文档和优先级，将条目以 JSON Lines 格式追加到本地文件。然后创建工具模式 ACTION_ITEM_TOOL_SCHEMA，包含类型、名称、描述和参数。在调用 responses.create 时，将工具模式加入 tools 列表。模型返回 function_call 时，解析参数并执行函数，即可将待办事项保存到磁盘。
OGX 如何实现从本地开发到生产部署的无缝切换？
OGX 采用可插拔的提供者架构，通过统一的 API 接口支持多种后端。开发时使用本地 Ollama 模型，生产环境只需更改模型字符串和提供者配置（如切换到 vLLM 或托管云服务），而向量存储逻辑、自定义工具和调度循环等应用代码完全无需重写。
