Building AI Applications with OGX, the Open-Source Agentic API Server

KDnuggets

KDnuggets2026年10月15日

Building AI Applications with OGX, the Open-Source Agentic API Server

6.9内容质量

TL;DR · AI 摘要

Building AI Applications with OGX, the Open-Source Agentic API Server - KDnuggets publ: 15-Oct, 2026 - Blog Top Posts Ab...

核心要点

主题聚焦：Building AI Applications with OGX, the Open-Sour
来源：KDnuggets，建议结合原文判断细节。
AI 分析暂不可用，本条为保底评分与摘要。

#AI#编程#前端#后端#云计算

打开原文

使用 OGX 开发 AI 应用，开源代理 API 服务器 - KDnuggets

publ: 2026年10月15日

博客热门文章

主题 AI 职业建议计算机视觉数据工程数据科学语言模型机器学习 MLOps NLP 编程 Python SQL

数据集

活动

资源快速参考指南推荐技术简报

广告

订阅电子报

#header end

/ad_wrapper

使用 OGX 开发 AI 应用，开源代理 API 服务器

OGX 是一个开源的代理 API 服务器，用于构建兼容 OpenAI 的 AI 应用，支持任意模型和任意基础设施。

作者：Shittu Olumide，技术内容专家发布于 2026年10月15日，语言模型类别

在了解这个主题之前需要知道的关键事实：OGX 是 Meta Llama Stack 的重新品牌化。其 GitHub 页面明确说明，Llama Stack 现在已更名为 OGX，这一名称变更伴随着使命的实质性转变——转向模型无关、多 SDK 支持和生产级应用，而不是一个架构相似但完全不同的新项目。这一事实为当前研究代理 API 服务器、兼容 OpenAI 的 API 或本地 AI 应用开发的任何人解决了大量困惑，因为关于 Llama Stack 的许多内容在 OGX 更名后依然适用。

OGX 是什么（以及为何之前称为 Llama Stack）

OGX 被明确描述为：一个开源的代理 API 服务器，用于构建兼容 OpenAI 的 AI 应用，支持任意模型和任意基础设施。该项目在 MIT 许可证下发布，是一个真正成熟的产品——截至本文撰写时，已在 GitHub 上获得超过 8,400 颗星标和 1,400 次分叉，拥有定期的社区会议和活跃的开发。

核心卖点是作为 OpenAI API 的即插即用替代方案，您可以在笔记本电脑、数据中心或云环境中自行运行它，并将任何兼容 OpenAI 的客户端或代理框架指向它。在单一 API 之下是可插拔的提供者架构：本地开发可对接 Ollama，生产部署可对接 vLLM，或连接托管云服务——所有操作都通过完全相同的 API 接口，因此后期更换后端无需重写应用。其功能不仅限于聊天补全：Responses API 可处理服务器端代理编排、工具调用、MCP 服务器集成，以及通过单个 API 调用实现内置文件搜索用于检索增强生成（RAG）。OGX 本机支持 OpenAI、Anthropic 和 Google GenAI SDK，所有操作都通过同一服务器完成，而不仅仅是某一家厂商的客户端库。

在本文中，我们将构建一个应用——暂且称之为 DocBrain——它具备两项功能。首先，真正的 RAG：上传文档后，它会根据文档的实际内容回答问题，检索过程自动完成，无需手动构建向量数据库和单独的检索脚本。其次，真正的代理能力：在审阅文档时，它可以调用自定义工具标记并保存实际的操作项——例如租约续签截止日期、后续任务——保存到磁盘上的实际文件中，而不仅仅是描述您应该做什么，而是真正完成记录工作。

code

# 安装 Ollama，然后拉取模型
ollama pull llama3.2:3b

# 设置真实项目（而非快速试用时的临时 uvx 命令）
uv init docbrain && cd docbrain
uv add ogx openai

代码说明：uv init 会生成一个规范的项目结构，而不是依赖一次性使用的 uvx 命令。当这个项目从五分钟实验转变为实际持续使用的工具时，这种区别就会变得非常重要。uv add ogx openai 会同时安装 OGX 服务端包和标准的 OpenAI Python 客户端，因为 DocBrain 与 OGX 通信只需要这个客户端。

启动服务器并验证运行状态

code

uv run ogx go

在 Ollama 已运行且模型已拉取的情况下，这会启动 OGX 服务器在 https://localhost:8321。在编写任何应用代码之前，请先确认服务器确实处于健康状态：

code

curl -k -s https://localhost:8321/v1/models | python -m json.tool

代码说明：OGX 默认使用 HTTPS 并开箱即用安全配置，因此本地测试需要使用 -k 参数跳过对自签名本地证书的验证。健康的响应会在 /v1/models 下列出已注册的模型，这验证了服务器已启动且 Ollama 连接正确，即使你尚未编写任何实际应用代码。

通过响应 API 实现基础聊天

最小的实用调用，为本教程后续所有内容建立模式基础：

code

import httpx
from openai import OpenAI

client = OpenAI(
    base_url="https://localhost:8321/v1",
    api_key="fake",
    http_client=httpx.Client(verify=False),
)

response = client.responses.create(
    model="ollama/llama3.2:3b",
    input="What is OGX?",
)
print(response.output_text)

代码说明：api_key="fake" 不是需要填充的占位符——对于本地服务器，OGX 根本不会验证这个密钥，任何字符串都可以。http_client=httpx.Client(verify=False) 是上一步 curl -k 参数的 Python 对应实现，用于本地开发时跳过证书验证。模型字符串采用 provider/model-name 格式——ollama/llama3.2:3b——这告诉 OGX 需要将请求路由到哪个配置好的提供方。response.output_text 是响应 API 的便捷属性，可直接获取最终文本答案，无需手动解析 choices 数组。

添加真实 RAG：上传文档并创建向量存储

这是 OGX 内置检索功能真正发挥作用的地方，实现方式非常简洁：

code

# 上传文档
file = client.files.create(
    file=open("lease_agreement.pdf", "rb"),
    purpose="assistants",
)

# 创建向量存储并索引文件
vector_store = client.vector_stores.create(
    name="docbrain-kb",
    file_ids=[file.id],
)

# 使用文件搜索提问
response = client.responses.create(
    model="ollama/llama3.2:3b",
    input="Summarize the key points",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id],
    }],
)
print(response.output_text)

代码说明：client.files.create 用于上传原始文档；purpose="assistants" 表示该文档内容用于可检索信息，而非微调数据集。client.vector_stores.create 是大多数 RAG 教程中手动编写数十行代码才能实现的核心步骤——将文档分块、对块进行嵌入编码并建立可搜索索引，这些操作均由 OGX 服务器端自动完成。responses.create 调用中的工具列表会触发针对该问题的检索功能：file_search 结合向量存储的 ID 告诉 OGX 在指定存储中搜索相关内容，并基于检索结果自动构建模型回答，最后生成响应。

添加自定义工具：标记并保存待办事项

这是 DocBrain 真正体现智能体特性的部分——一个模型可自主调用的真实 Python 函数。

code

# tools/action_items.py
import json
import os
from datetime import datetime, timezone

ACTION_ITEMS_FILE = "action_items.jsonl"

def save_action_item(description: str, source_document: str, priority: str = "medium") -> dict:
    """将一条待办事项以 JSON 行格式追加到本地文件。"""
    if not description.strip():
        raise ValueError("description cannot be empty")
    if priority not in ("low", "medium", "high"):
        raise ValueError(f"priority must be low, medium, or high, got '{priority}'")

    entry = {
        "description": description.strip(),
        "source_document": source_document.strip(),
        "priority": priority,
        "flagged_at": datetime.now(timezone.utc).isoformat(),
    }
    with open(ACTION_ITEMS_FILE, "a") as f:
        f.write(json.dumps(entry) + "\n")
    return {"status": "saved", "entry": entry}

def list_action_items() -> list[dict]:
    """读取所有已保存的待办事项，若文件不存在则返回空列表。"""
    if not os.path.exists(ACTION_ITEMS_FILE):
        return []
    with open(ACTION_ITEMS_FILE) as f:
        return [json.loads(line) for line in f if line.strip()]
    

ACTION_ITEM_TOOL_SCHEMA = {
    "type": "function",
    "name": "save_action_item",
    "description": (
        "保存在审阅文档时发现的真实可执行待办事项。"
        "仅在存在真实可操作任务时调用，而非一般性总结要点。"
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "description": {"type": "string", "description": "具体的待办事项，用一句话描述"},
            "source_document": {"type": "string", "description": "该事项来源的上传文档"},
            "priority": {"type": "string", "enum": ["low", "medium", "high"]},
        },
        "required": ["description", "source_document"],
    },
}

代码说明：save_action_item 在写入任何内容之前会先验证自己的输入——空的描述或无效的优先级值会立即引发错误，而不是悄无声息地破坏保存的文件。将条目存储为 JSON Lines（每行一个 JSON 对象，追加写入）而非一个大型 JSON 数组是一个经过深思熟虑的实用选择：追加一行操作简单且安全，即使在写入过程中被中断也不会导致数据损坏；而向 JSON 数组追加内容则需要每次读取、修改并重写整个文件。ACTION_ITEM_TOOL_SCHEMA 是模型实际看到的该函数的描述——在这里，一个精确具体的描述（"仅对真实可执行的任务调用此功能"）非常重要，因为模糊的工具描述往往会导致模型对非真正可执行的事项产生过度触发。

组合完整助手

code

# docbrain.py
import httpx
import json
from openai import OpenAI
from tools.action_items import save_action_item, ACTION_ITEM_TOOL_SCHEMA

client = OpenAI(
    base_url="https://localhost:8321/v1",
    api_key="fake",
    http_client=httpx.Client(verify=False),
)
MODEL = "ollama/llama3.2:3b"

def setup_knowledge_base(file_paths: list[str]) -> str:
    file_ids = []
    for path in file_paths:
        uploaded = client.files.create(file=open(path, "rb"), purpose="assistants")
        file_ids.append(uploaded.id)
    vector_store = client.vector_stores.create(name="docbrain-kb", file_ids=file_ids)
    return vector_store.id

def ask(question: str, vector_store_id: str) -> str:
    response = client.responses.create(
        model=MODEL,
        input=question,
        tools=[
            {"type": "file_search", "vector_store_ids": [vector_store_id]},
            ACTION_ITEM_TOOL_SCHEMA,
        ],
    )
    for item in response.output:
        if getattr(item, "type", None) == "function_call" and item.name == "save_action_item":
            args = json.loads(item.arguments)
            save_action_item(**args)
    return response.output_text

if __name__ == "__main__":
    vector_store_id = setup_knowledge_base(["lease_agreement.pdf", "vendor_contract.pdf"])
    answer = ask(
        "Summarize the key terms of these documents, and flag anything "
        "that needs action before a deadline.",
        vector_store_id,
    )
    print(answer)

代码说明：file_search 工具和自定义的 save_action_item 工具在同一个 API 调用的工具列表中并存，这正是 Responses API 设计的核心要点：检索和自定义工具调用不是两个独立系统拼接而成，而是作为工具列表中的两个条目，由模型统一进行推理。对 response.output 的遍历使工具真正具备功能性而非装饰性：它会检查模型生成的每个项目，任何匹配 save_action_item 的 function_call 都会解析参数并实际执行，将真实的一行内容写入磁盘上的 action_items.jsonl 文件。

运行完整项目

在 Ollama 运行并拉取模型后，启动服务器，然后使用自己的文档运行助手：

code

uv run ogx go          # 在一个终端中
uv run python docbrain.py    # 在另一个终端中，当服务器健康运行后

替换 lease_agreement.pdf 和 vendor_contract.pdf 为你的文件。向它提出真实的问题。如果在回答过程中发现真实的截止日期或任务，请后续查看 action_items.jsonl 文件——那里会保存真实的记录，而不仅仅是终端中滚动过去的文字。

总结

OGX 演示真正值得认真对待的真正原因并非本教程中的任何单一功能，而是后续会发生的事情。我们在此构建的应用程序完全基于本地 Ollama 模型运行，且成本为零。当你需要生产级可靠性时，转向 vLLM 或托管服务提供商只需更改模型字符串和提供商配置，而无需重写应用程序。向量存储逻辑、工具、调度循环——所有内容都保持原样不变。

这就是 API 封装器与真正的智能代理平台之间的真正区别，也是为什么这个项目值得继续构建，而不是在需要扩展时就放弃。

Shittu Olumide 是一位软件工程师和技术作家，热衷于利用前沿技术创作引人入胜的叙事，注重细节并擅长简化复杂概念。你也可以在 Twitter 上找到 Shittu。

Building AI Applications with OGX, the Open-Source Agentic API Server

TL;DR · AI 摘要

核心要点

使用 OGX 开发 AI 应用，开源代理 API 服务器 - KDnuggets

使用 OGX 开发 AI 应用，开源代理 API 服务器

OGX 是什么（以及为何之前称为 Llama Stack）

启动服务器并验证运行状态

通过响应 API 实现基础聊天

添加真实 RAG：上传文档并创建向量存储

添加自定义工具：标记并保存待办事项

组合完整助手

运行完整项目

总结

更多相关内容

最新文章

热门文章