使用 Ollama 在本地运行 AI Agent — 不需要 API Key背景如果你的目标是学习 Agent 概念、

背景

如果你的目标是学习 Agent 概念、测试架构设计、做技术调研，根本不需要付费 API。Ollama 可以让你在本地电脑上运行开源大模型，并且提供 OpenAI 兼容的 API 接口，主流 Agent 框架都能直接对接。

本文介绍如何用 Ollama 搭建一个完全本地化的 AI Agent 开发环境。无需 API Key，无需联网，无需任何费用。

三种方案怎么选

方案	适用场景	成本	前置条件
Ollama（本文）	学习、调研、架构实验、离线开发	免费	本地机器 8GB+ 内存
Claude Agent SDK	需要 Claude 级别智能的内部原型验证	共享订阅额度	Claude Code CLI + Enterprise 登录
LLM Gateway API	生产环境、对外服务	按 token 计费	审批 API Key

简单原则：先用 Ollama 验证想法、理解 Agent 运行机制。需要 Claude 级别推理能力时切换到 Agent SDK。上生产时申请 LLM Gateway API。

Ollama 是什么

Ollama 是一个开源的本地大模型运行工具，封装了 llama.cpp，提供简单的 CLI 和内置的 OpenAI 兼容 API 服务（http://localhost:11434）。核心特点：

支持 Llama、Qwen、Mistral、DeepSeek、Gemma、Phi 等主流模型系列
GPU 加速：NVIDIA (CUDA)、Apple Silicon (Metal)、AMD (ROCm)
内置 Tool Calling / Function Calling 支持（需要模型本身支持）
OpenAI 兼容 API — 改个 base_url 就能用，框架代码不用改
CLI 管理模型：ollama pull、ollama run、ollama list

快速开始

第一步：安装 Ollama

macOS / Linux:

curl -fsSL https://ollama.com/install.sh | sh

Windows:

winget install Ollama.Ollama

验证安装：

ollama --version

第二步：拉取模型

Agent 开发需要支持 Tool Calling 的模型，推荐：

# 推荐：Qwen3.5 9B — 最新一代，原生视觉 + Tool Calling + Thinking，256K 上下文
ollama pull qwen3.5:9b

# 轻量替代：Qwen3.5 4B — 8GB 内存机器也能跑
ollama pull qwen3.5:4b

# 更强推理能力（需要 24GB+ 内存）：Qwen3.5 27B
ollama pull qwen3.5:27b

# MoE 选项 — 总参数 35B 但仅激活 3B，22GB 设备可运行
ollama pull qwen3.5:35b

硬件参考：qwen3.5:9b 约 6.6GB（大部分 16GB 机器轻松运行）。qwen3.5:4b 约 3.4GB（8GB 内存笔记本也行）。qwen3.5:27b 和 35b 需要 24GB+ 内存/显存。16GB 的 Apple Silicon Mac 可以流畅运行 9B 模型。

第三步：验证 API

Ollama 启动后自动提供 API 服务，测试一下：

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5:9b",
    "messages": [
      {"role": "user", "content": "你好！"}
    ]
  }'

收到 JSON 回复就说明环境就绪。

使用 Ollama 构建 Agent

Ollama 的 OpenAI 兼容 API 意味着你可以无缝接入任何支持 OpenAI 格式的框架。以下是最常用的几种模式。

模式 A — 直接用 OpenAI SDK（最简单）

官方 OpenAI Python SDK 可以直接对接 Ollama，只需改 base_url：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # SDK 要求填写，但 Ollama 不校验
)

response = client.chat.completions.create(
    model="qwen3.5:9b",
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手。"},
        {"role": "user", "content": "用3句话解释什么是 AI Agent。"},
    ],
)
print(response.choices[0].message.content)

模式 B — Tool Calling / Function Calling

Agent 开发的核心 — 让模型自主决定何时调用外部工具：

import json
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的当前天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称"}
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="qwen3.5:9b",
    messages=[{"role": "user", "content": "香港今天天气怎么样？"}],
    tools=tools,
)

msg = response.choices[0].message
if msg.tool_calls:
    for call in msg.tool_calls:
        print(f"模型要调用: {call.function.name}")
        print(f"参数: {call.function.arguments}")
else:
    print(msg.content)

模式 C — 完整 Agent 循环

一个最小化的 Agent 循环，展示完整流程：用户输入 → 模型推理 → 工具执行 → 模型综合回答：

import json
from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

# 模拟工具实现
def get_weather(city: str) -&gt; str:
    return json.dumps({"city": city, "temp": "28°C", "condition": "晴"})

def search_docs(query: str) -&gt; str:
    return json.dumps({"results": [f"找到关于 '{query}' 的文档"]})

TOOL_MAP = {"get_weather": get_weather, "search_docs": search_docs}

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的当前天气",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "search_docs",
            "description": "按关键词搜索内部文档",
            "parameters": {
                "type": "object",
                "properties": {"query": {"type": "string"}},
                "required": ["query"],
            },
        },
    },
]

def agent_run(user_input: str):
    messages = [
        {"role": "system", "content": "你是一个有帮助的助手，需要时使用工具。"},
        {"role": "user", "content": user_input},
    ]

    # 第一步：模型初次调用
    response = client.chat.completions.create(
        model="qwen3.5:9b", messages=messages, tools=tools
    )
    msg = response.choices[0].message
    messages.append(msg)

    # 第二步：如果模型请求调用工具，执行它
    if msg.tool_calls:
        for call in msg.tool_calls:
            fn = TOOL_MAP.get(call.function.name)
            if fn:
                result = fn(**json.loads(call.function.arguments))
                messages.append({
                    "role": "tool",
                    "tool_call_id": call.id,
                    "content": result,
                })

        # 第三步：模型综合工具结果生成最终回答
        final = client.chat.completions.create(
            model="qwen3.5:9b", messages=messages, tools=tools
        )
        return final.choices[0].message.content

    return msg.content

# 试试
print(agent_run("香港今天天气怎么样？"))
print(agent_run("帮我搜索 Agent 架构相关文档"))

这就是所有 Agent 框架背后的基本模式。理解了这个循环，就可以逐步构建更复杂的 Agent。

可选：LiteLLM 统一网关

大部分本地开发场景 Ollama 就够了。但如果你需要：

在多个模型之间路由（例如本地 Ollama + 云端备选）
添加日志、成本追踪、限流
用同一套代码测试多种模型后端

可以用 LiteLLM 作为 Ollama 前面的代理：

pip install litellm[proxy]

# 启动代理，指向本地 Ollama
litellm --model ollama/qwen3.5:9b --port 8000

然后应用指向 http://localhost:8000，代码还是标准 OpenAI SDK 格式，不需要任何改动。

当你的 Agent 代码不变但想通过配置而非代码来切换本地（Ollama）和云端（LLM Gateway）模型时，LiteLLM 很有用。

优势

零成本：不需要 API Key，不产生 token 费用，不消耗订阅额度。本机硬件跑多少都行。
完全隐私：数据完全在本地，不需要联网。用什么数据做实验都没有隐私顾虑。
理解原理：直接使用开源模型，能真正理解 Tool Calling、上下文管理、Agent 循环是怎么运作的，不被商业 API 的抽象挡住。
框架无关：Ollama 的 OpenAI 兼容 API 支持 LangChain、LlamaIndex、CrewAI、AutoGen、smolagents 等几乎所有主流框架。
快速迭代：没有速率限制，没有网络延迟。启动模型、测试、调整、重复。

限制与注意事项

模型能力差距：开源 8B–32B 模型在复杂推理、长上下文、精确 Tool Calling 上与 Claude Sonnet/Opus 有明显差距。工具参数生成和指令遵循的出错率更高。
Tool Calling 可靠性：并非所有模型的 Tool Calling 都一样好。Qwen3.5、Llama 3.3、GLM-4 支持最好。小模型（<9B）容易出现工具调用幻觉或参数遗漏。Agent 任务建议 temperature 设为 0–0.2。
硬件要求：本地跑模型需要 CPU/GPU 和内存资源。8B 模型大部分机器没问题。32B+ 模型需要较强硬件（32GB+ 内存或 24GB+ 显存的独立显卡）。
不适合生产：本方案用于开发、学习和研究。生产服务请使用 LLM Gateway API，有 SLA、计费和监控保障。
无内置 MCP 支持：与 Claude Code 不同，Ollama 不原生集成 MCP Server。需要在 Agent 代码中自行实现 MCP 客户端逻辑，或使用支持 MCP 的框架。

从本地到生产

在本地用 Ollama 验证 Agent 设计后，切换到生产环境非常简单，因为 API 接口格式一致：

切换到 Claude Agent SDK 做内部测试 — 只需更换认证方式，代码结构不变。
切换到 LLM Gateway API 上生产 — 把 base_url 改成网关地址，api_key 填网关密钥。同样的 OpenAI SDK 代码，不同的端点。

# 本地开发（Ollama）
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

# 生产环境（LLM Gateway）
client = OpenAI(base_url="https://&lt;gateway-url&gt;/v1", api_key="your-gateway-key")

Agent 逻辑、工具定义、提示词完全不变。这就是基于 OpenAI 兼容 API 标准构建的核心好处。

Agent 开发推荐模型

模型	参数量	Tool Calling	适用场景	最低内存
qwen3.5:9b	9B	好	日常 Agent 开发、实验、代码任务	8GB
qwen3.5:4b	4B	一般	硬件受限时的轻量测试	8GB
qwen3.5:27b	27B	很好	复杂推理、接近生产级测试	24GB
qwen3.5:35b	35B (MoE, 3B 激活)	很好	较强能力 + 中等硬件要求	22GB
llama3.3:8b	8B	好	通用任务	8GB

运行 ollama list 查看已安装模型，ollama pull <model> 下载新模型。

参考资源

Ollama 官网：ollama.com
Ollama OpenAI 兼容 API：docs.ollama.com/api/openai-…
Ollama Tool Calling：docs.ollama.com/capabilitie…
Ollama 模型库：ollama.com/library
LiteLLM 代理：docs.litellm.ai/docs/simple…
Open WebUI（Ollama 的可选图形界面）：github.com/open-webui/…