告别API Key和云账单：NOOA本地模型部署（Ollama/vLLM）3步完全指南-开发者社区

告别API Key和云账单：NOOA本地模型部署（Ollama/vLLM）3步完全指南

【免费下载链接】labs-OO-AgentsNVIDIA Object Oriented Agents: the Pythonic way to build AI Agents.项目地址: https://gitcode.com/gh_mirrors/la/labs-OO-Agents

NOOA（NVIDIA Object Oriented Agents）是一个面向 AI Agent 开发的 Python 对象式框架。本文将带你用 Ollama 或 vLLM 在本地部署大模型并接入 NOOA——全程无需 API Key，不产生任何云端账单，数据也不离开你的电脑。

为什么选择本地模型？

对于新手和个人开发者，本地模型有三大优势：

优势	说明
💰 零调用费用	每次 LLM 生成都按 token 计费的时代，本地推理成本只算电费
🔒 数据不出门	敏感文档、内部数据不会被发送到第三方 API
📡 离线可用	断网环境、内网服务器同样能跑 Agent

NOOA 本身是模型无关的：它通过 src/nooa/unifiedllm/registry.py 中的get_llm_client()统一接入任意模型，包括本地服务。也就是说，把云端模型换成本地模型，只需要改一行客户端配置，Agent 代码完全不用动。

方式一：用 Ollama 部署本地模型（最简单）

Ollama 是面向本地大模型的"包管理器 + 运行时"，一条命令就能拉模型、起服务，非常适合新手。

第 1 步：启动 Ollama 服务

ollama serve

第 2 步：拉取一个模型

ollama pull qwen3.6:27b

硬件不够？换成更小的模型（如qwen3:1.7b）即可，先用ollama list确认模型名。

第 3 步：在 NOOA 中接入

from nooa.unifiedllm.registry import get_llm_client llm = get_llm_client( "ollama_chat/qwen3.6:27b", api_base="http://localhost:11434", )

三个要点：

模型字符串使用ollama_chat/前缀，对应 LiteLLM 的 Ollama 适配器；
api_base填本地端口地址，不带/v1；
本地 Ollama 无需 API Key。

方式二：用 vLLM 部署本地模型（性能更强）

vLLM 适合追求吞吐量和并发能力的场景，性能通常优于 Ollama，但对 GPU 显存要求更高。

第 1 步：启动 vLLM 服务

vllm serve Qwen/Qwen3.6-27B --host 127.0.0.1 --port 8000

第 2 步：验证服务是否就绪

curl http://localhost:8000/v1/models

能列出模型即表示服务正常。

第 3 步：在 NOOA 中接入

llm = get_llm_client( "hosted_vllm/Qwen/Qwen3.6-27B", api_base="http://localhost:8000/v1", )

与 Ollama 的两个关键差异：

模型字符串使用hosted_vllm/前缀，模型 ID 取/v1/models返回的值；
api_base带/v1后缀；
若 vLLM 以--api-key或VLLM_API_KEY启动，把同一个 key 传给api_key参数即可。

⚠️ 安全提示：只有在你已配置身份认证和网络访问控制时，才把 vLLM 绑定到0.0.0.0，否则保持默认的127.0.0.1。

一次配置永久生效：模型别名

每次写api_base很啰嗦？NOOA 支持把本地配置存为别名，写入用户配置目录下的llm_config.yaml（例如.nooa/llm_config.yaml）：

models: local-ollama: model_name: ollama_chat/qwen3.6:27b api_base: http://localhost:11434 local-vllm: model_name: hosted_vllm/Qwen/Qwen3.6-27B api_base: http://localhost:8000/v1

之后任意 Agent 只需一行拿到客户端：

llm = get_llm_client("local-ollama")

更多字段的规范（client_type、api_key_env、max_tokens等）请参考 docs/model-configuration.md。

不花一分钱验证配置

保存别名后，可以先做零 API 调用的本地校验，确认别名已正确加载：

from pathlib import Path from nooa.unifiedllm.registry import reload_registry entries = reload_registry(Path("llm_config.yaml")) assert "local-ollama" in entries print("Model configuration loaded.")

如果之后想对端点做完整的连通性检查，可以用nooa connect向导并加--no-probe --no-catalogue参数，跳过所有会消耗模型的探测请求，详见 docs/model-connect.md。

接入后跑通你的第一个本地 Agent

客户端就绪后，把它挂到 Agent 类上即可，参考官方示例 examples/quickstart/01_first_generation_method.py：

class FeedbackAgent(Agent, llm=llm): """You are an agent specializing in analyzing customer feedback.""" async def analyze_feedback(self, text: str) -> str: """Analyze customer feedback for sentiment and key topics in one sentence.""" ...

方法体里的...表示由 LLM 在运行时实现——你的模型名、参数和 docstring 就是提示词，返回类型注解就是输出契约。本地模型跑起来后，整个 Agent 循环完全在你的机器上完成。

常见坑清单

问题	排查方法
连接被拒绝	确认`ollama serve`/`vllm serve`已启动，端口号一致
Ollama 报 404	模型名必须与`ollama list`输出完全一致
vLLM 返回 404	检查`api_base`是否带了`/v1`，模型 ID 是否为`/v1/models`返回的 id
本地模型效果差	小模型能力有限，可换更大规格或升级显存