在 agno 中使用 N1N 模型：OpenAI 兼容集成实战指南

在 agno 中使用 N1N 模型：OpenAI 兼容集成实战指南

【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno

导读

本文以 agno 仓库中 cookbook/90_models/n1n 的 cookbook 示例为核心，讲解如何在 agno Agent 中接入 N1N 这一 OpenAI 兼容的模型提供商。你将掌握N1N模型类的环境变量配置、基础对话与流式输出、工具调用三个核心能力，并通过源码级剖析理解其认证机制与底层调用链，最终能够将 N1N 模型无缝替换进自己的 agno 应用中。

N1N 集成概览

N1N 是一个使用 OpenAI API 协议的服务提供商，agno 为其提供了开箱即用的模型封装。在 agno 中，N1N类位于 libs/agno/agno/models/n1n/n1n.py，并在 libs/agno/agno/models/n1n/init.py 中导出。

从源码结构看，N1N的继承链为N1N → OpenAILike → OpenAIChat → Model：

• OpenAILike 是 agno 为"使用 OpenAI API schema 的任何第三方提供商"设计的基类，因此 N1N 天然获得完整的 OpenAI 协议支持，包括 Chat Completions、流式输出、结构化输出与工具调用；
• OpenAIChat 提供底层的客户端管理与请求封装。

N1N类自身的默认配置如下（见 n1n.py）：

属性	默认值	说明
id	"gpt-4o"	模型标识，可选gpt-5.6-luna、gpt-5-mini等
name	"N1N"	模型显示名称
provider	"N1N"	提供商名称
api_key	环境变量N1N_API_KEY	认证密钥，未显式传入时从环境变量读取
base_url	"https://api.n1n.ai/v1"	API 端点地址

环境准备：安装与 API Key

在使用 N1N 模型之前，需要完成两步准备工作。

第一步：安装 agno 及 WebSearch 工具依赖（工具调用示例需要）：

pip install -U agno agno-tools

第二步：设置 N1N API Key 环境变量。N1N模型类的api_key字段通过getenv("N1N_API_KEY")读取（见 n1n.py）：

export N1N_API_KEY=your-api-key-here

值得强调的是，如果你没有设置N1N_API_KEY，agno 并不会在创建 Agent 时立即报错，而是在真正发起请求、调用_get_client_params()构建客户端参数时才抛出ModelAuthenticationError，错误信息为 "N1N_API_KEY not set. Please set the N1N_API_KEY environment variable."（见 n1n.py）。这一点已被 test_n1n.py 中的test_n1n_initialization_without_api_key用例明确验证。

基础对话：创建 Agent 并运行

cookbook 示例 basic.py 演示了使用 N1N 模型创建 agno Agent 的最小完整流程，核心代码只有三行：

from agno.agent import Agent from agno.models.n1n import N1N agent = Agent(model=N1N(id="gpt-5.6-luna"), markdown=True)

关键点说明：

• N1N(id="gpt-5.6-luna")：显式指定模型 ID。cookbook 中选用了gpt-5.6-luna，实际可选 ID 以 N1N 平台提供为准；省略id参数时默认使用"gpt-4o"；
• markdown=True：让 Agent 以 Markdown 格式渲染输出，便于阅读。

示例同时演示了同步模式与同步 + 流式（streaming）模式两种运行方式：

if __name__ == "__main__": # --- 同步模式 --- agent.print_response("Share a 2 sentence horror story.") # --- 同步 + 流式模式 --- agent.print_response("Share a 2 sentence horror story.", stream=True)

两种模式通过print_response的stream参数切换：stream=False（默认）时等待完整响应后一次性打印；stream=True时启用流式输出，Token 逐个到达并实时展示，适合对响应延迟敏感的场景。

运行 cookbook 示例（README 中给出的标准命令）：

.venvs/demo/bin/python cookbook/90_models/n1n/basic.py

工具调用：让 N1N Agent 联网搜索

N1N 模型基于 OpenAI 协议实现函数调用能力，这意味着你可以直接为 Agent 挂载 agno 工具包。cookbook 示例 tool_use.py 展示了将WebSearchTools挂载到 N1N Agent 上的完整用法：

from agno.agent import Agent from agno.models.n1n import N1N from agno.tools.websearch import WebSearchTools agent = Agent( model=N1N(id="gpt-5-mini"), markdown=True, tools=[WebSearchTools()], ) agent.print_response("What is happening in France?", stream=True)

工作流程如下：

1. 用户提问 "What is happening in France?"；
2. Agent 判断该问题需要实时信息，向 N1N 模型发起包含工具定义的请求；
3. 模型返回工具调用指令，Agent 执行WebSearchTools检索网页；
4. 检索结果回传给模型，模型综合生成最终回答并流式输出。

注意该示例在模块顶层直接调用agent.print_response(...)，if __name__ == "__main__":块为空，因此直接运行脚本即可触发一次完整的"搜索 + 回答"流程：

.venvs/demo/bin/python cookbook/90_models/n1n/tool_use.py

源码级剖析：N1N 的认证与客户端构建

要深入理解 N1N 集成，核心在 n1n.py 中的_get_client_params()方法，它覆盖了OpenAIChat的同名方法，专门处理 N1N 的 API Key 与基础连接参数：

def _get_client_params(self) -> Dict[str, Any]: # 1. 若未显式传入 api_key，则从环境变量获取 if not self.api_key: self.api_key = getenv("N1N_API_KEY") if not self.api_key: # 2. Key 缺失时立即抛出认证错误 raise ModelAuthenticationError( message="N1N_API_KEY not set. Please set the N1N_API_KEY environment variable.", model_name=self.name, ) # 3. 组装基础客户端参数 base_params = { "api_key": self.api_key, "organization": self.organization, "base_url": self.base_url, "timeout": self.timeout, "max_retries": self.max_retries, "default_headers": self.default_headers, "default_query": self.default_query, } # 4. 过滤掉值为 None 的参数，避免污染 OpenAI 客户端 client_params = {k: v for k, v in base_params.items() if v is not None} # 5. 允许用户通过 client_params 注入额外参数（优先级最高） if self.client_params: client_params.update(self.client_params) return client_params

这段代码揭示了几条重要实现事实：

• 认证优先级：显式传入的api_key优先于环境变量；两者皆无才抛错；
• 参数过滤：值为None的字段会被剔除，确保 OpenAI 客户端不会收到无效参数；
• 可扩展性：timeout、max_retries、default_headers、default_query等字段均继承自 OpenAIChat，可在构造N1N时直接覆盖。例如需要加大请求超时与重试次数时，可这样配置：

from agno.agent import Agent from agno.models.n1n import N1N agent = Agent( model=N1N( id="gpt-5.6-luna", timeout=60.0, # 请求超时（秒） max_retries=3, # 失败重试次数 ), markdown=True, )

• 客户端构建链路：_get_client_params()的返回值会传入 OpenAIChat 的OpenAIClient(**client_params)与AsyncOpenAIClient(**client_params)调用，用于创建同步与异步两个 OpenAI 客户端实例。因此 N1N Agent 既支持print_response同步调用，也支持异步接口，与官方 OpenAI 模型在 agno 中的使用体验完全一致。

测试验证：单元测试保障集成正确性

仓库在 libs/agno/tests/unit/models/test_n1n.py 中为 N1N 集成提供了 4 个单元测试，覆盖了关键行为：

测试用例	验证内容
test_n1n_initialization_with_api_key	显式传入 API Key 时，模型id、api_key、base_url均正确设置
test_n1n_initialization_without_api_key	清空环境变量后，调用_get_client_params()抛出ModelAuthenticationError
test_n1n_initialization_with_env_api_key	仅设置N1N_API_KEY环境变量时，模型自动读取该值
test_n1n_client_params	_get_client_params()返回的api_key与base_url与预期一致

其中test_n1n_client_params直接断言了client_params["base_url"] == "https://api.n1n.ai/v1"，从测试层面锁定了默认端点地址。这些测试可作为你验证本地环境配置是否正确的参考：运行以下命令即可执行：

python -m pytest libs/agno/tests/unit/models/test_n1n.py -v

总结与进阶方向

至此，你已完整掌握在 agno 中集成 N1N 模型的三步走：

1. 配置：安装 agno、导出N1N_API_KEY；
2. 接入：Agent(model=N1N(id=...))，用stream=True切换流式输出；
3. 增强：挂载WebSearchTools等工具，让模型具备实时检索能力。

由于N1N完全复用 OpenAI 协议，所有 agno 的通用能力——结构化输出、记忆与存储、多 Agent 团队协作、Workflow 编排等——均可直接应用于 N1N 模型，无需任何额外适配。若需进一步探索，可阅读 agno 的模型基类 libs/agno/agno/models/base.py 了解 Agent 与模型的完整交互契约，或参考仓库中其他基于OpenAILike实现的提供商（如 libs/agno/agno/models/xai、libs/agno/agno/models/openrouter）对比各自的定制方式。

【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno