构建本地 AI 智能体：架构与推荐工具

#为什么要构建本地 AI 智能体

本地 AI 智能体满足了云端难以妥善处理的三项需求。首先是隐私：当智能体读取您的邮件、查询您的数据库或浏览您的文件时，每一次发送到外部 API 的调用都可能造成信息泄露。在本地运行时，上下文绝不会离开这台机器。其次是成本：智能体完成一项任务就要连续调用模型数十次，按使用量计费的 API 费用很快就会飙升。最后是自主性：没有请求速率限制，不会因网络中断而停摆，也不会遭遇定价政策一夜之间改变的情况。

确实需要付出代价：140 亿或 320 亿参数的本地模型，推理不如最优秀的专有模型细致。因此，智能体的设计——合理划分工具、严格的提示词、防护措施——比在云端更为重要。这正是这篇本地 AI 智能体指南所涵盖的内容。

#智能体的组成结构

无论使用哪种框架，本地 AI 智能体始终依赖相同的基础组件。理解这些组件，才能在充分了解的基础上选择工具，而不是盲目照着教程操作。

模型（推理）

决定下一步行动的 LLM。它必须可靠地处理工具调用：Qwen 3.x、Granite 4.x 或 Mistral Small 是本地环境中的良好选择

工具（操作）

智能体可以调用的 Python 函数：读取文件、请求 API、执行搜索、写入数据库。每个工具都通过模型会读取的 JSON 模式来描述。

记忆（状态）

短期（当前对话历史）和长期（跨会话持久的向量存储）。这是 RAG 的作用，下文将详细说明。

编排器（循环）

将推理、工具调用和观察依次串联起来，循环执行直到满足停止条件的代码。CrewAI 或 AutoGen 这类框架提供的就是这种代码。

规划器（策略）

将复杂目标拆分为有序子任务的逻辑。它可以是显式的（由专用的规划智能体负责），也可以是隐式的（模型逐步推理）。

一个最简智能体只需一个模型、两三个工具和一个循环。高级系统则会加入持久化记忆、多步骤规划，以及多个协同工作的专门智能体。从简单方案开始：大多数任务并不需要一支由十个智能体组成的团队。

#先决条件和推荐技术栈

本地 AI 智能体的参考技术栈包含三层：提供模型推理服务的 Ollama、一个 Python 编排框架，以及一个支持工具调用的模型。Ollama 默认监听 http://localhost:11434，并提供兼容 OpenAI 的端点，从而简化与大多数框架的集成。

GPU / VRAM

使用14B以上模型的智能体比7B模型推理效果更好。14B模型在Q4_K_M量化下约需9GB VRAM，32B模型约需19GB。RTX 4070 12GB显卡可流畅运行14B模型；RTX 4090 24GB或Mac M4 Pro则可支持32B模型。

模型

选择一个在工具调用方面以可靠著称的模型。函数调用的质量比单纯的模型规模更重要：一个严谨的 14B 模型胜过一个编造参数的 32B 模型。

Python 3.10+

CrewAI 和 AutoGen 是 Python 库。建议在专用虚拟环境中工作，以避免依赖冲突。

Quantization

Q4_K_M 是默认的合理选择。若模型出现推理错误且 VRAM 允许，可升级至 Q5_K_M 或 Q8_0。

# 1. Vérifier qu'Ollama tourne
curl http://localhost:11434/api/tags

# 2. Récupérer un modèle capable de tool calling
ollama pull qwen3:14b

# 3. Environnement Python isolé
python -m venv .venv && source .venv/bin/activate
pip install crewai crewai-tools

#CrewAI 还是 AutoGen：选哪个？

两个框架都能编排智能体，但设计理念不同。合适的选择取决于你的任务，而不是某个绝对排名。

CrewAI

以“团队”为导向：为智能体定义角色、目标和工具，然后分配按顺序执行的任务。采用声明式方式，清晰易读，非常适合业务流程（研究 → 撰写 → 审阅）。内置 RAG 记忆。

AutoGen

以“对话”为核心：智能体相互交流，直到达成一致。对于开放性问题和协作推理，这种方式更灵活，但需要更多调校，才能在本地运行时控制好范围。v0.4 通过其兼容 OpenAI 的客户端连接 Ollama。

何时保持简单

对于配备少量工具的单个智能体，轻量级框架（或 LangChain）就足够了。一旦涉及多个角色或较复杂的编排，CrewAI 和 AutoGen 就能充分发挥作用。

from crewai import Agent, Task, Crew, LLM

# CrewAI passe par LiteLLM : préfixe 'ollama/' + base_url local
llm = LLM(
    model="ollama/qwen3:14b",
    base_url="http://localhost:11434",
)

chercheur = Agent(
    role="Analyste documentaire",
    goal="Extraire les faits clés des documents fournis",
    backstory="Expert méthodique, ne répond que sur la base des sources.",
    llm=llm,
    verbose=True,
)

tache = Task(
    description="Résume les 3 points essentiels du rapport fourni.",
    expected_output="Une liste à puces de 3 points, sourcés.",
    agent=chercheur,
)

equipe = Crew(agents=[chercheur], tasks=[tache])
print(equipe.kickoff())

from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_agentchat.agents import AssistantAgent

# Endpoint OpenAI-compatible d'Ollama : /v1
client = OpenAIChatCompletionClient(
    model="qwen3:14b",
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # ignore par Ollama, mais requis par le client
    model_info={
        "function_calling": True,
        "json_output": True,
        "vision": False,
        "family": "unknown",
    },
)

agent = AssistantAgent(name="assistant", model_client=client)

#逐步构建智能体

以下是将原始模型转化为能够完成实际任务的本地 AI 智能体的步骤。顺序很重要：每一步都会验证前一步。

1. 01
   设定目标及停止条件

   用一句话写清楚智能体应产出什么，以及如何判断它已经完成任务。模糊的目标（如“帮帮我”）会让智能体原地打转；有明确边界的目标（如“将这 20 张发票按供应商分类，整理成一个 CSV 文件”）则能让智能体的行为可控。
2. 02
   拆分为原子工具

   每个外部操作都对应一个 Python 函数，函数应有明确的名称、带类型标注的参数和清晰的文档字符串——模型读取的正是这段说明。优先使用多个功能明确的小工具，而不是一个包揽各种功能的大工具。
3. 03
   编写系统提示

   明确角色、可用工具和规则（绝不编造，始终引用来源，有疑问时停止）。在本地运行时，严格的提示词可以弥补模型推理不够细致的不足。
4. 04
   搭建编排循环

   让框架管理推理 → 行动 → 观察的循环，但要设置迭代次数上限（例如 10 次），以免陷入停滞的智能体无限消耗资源。这是智能体自主运行时不可或缺的防护措施。
5. 05
   添加记忆功能

   如果智能体需要跨会话记住信息，请连接向量存储以实现长期记忆（参见下一节）。如果没有这一需求，对话历史就足够了。
6. 06
   在真实场景中测试并迭代

   用多种不同的输入运行智能体，查看执行跟踪记录（verbose），修正提示词和工具描述。开发本地智能体的 80% 工作都在这一阶段，而非编写最初的代码。

#通过RAG实现长期记忆

没有记忆的智能体每次会话都会从零开始。长期记忆与 RAG（检索增强生成）基于相同的原理：将信息以向量形式存入数据库，在需要时检索最相关的信息，再将其加入上下文。

本地嵌入

使用由 Ollama 提供的嵌入模型（例如nomic-embed-text或mxbai-embed-large）生成向量：待存储的数据不会离开本地设备，符合隐私保护目标。

向量存储

ChromaDB 是本地环境下的默认选择：轻量、持久存储于磁盘、原生集成于 CrewAI。对于更大规模的数据，Qdrant 自托管版本将接替其角色。

CrewAI 内置记忆功能

CrewAI 提供开箱即用的记忆功能（短期记忆、长期记忆和实体记忆），可配置为使用 Ollama 嵌入模型，无需手动搭建 RAG 流水线。

from crewai import Crew

equipe = Crew(
    agents=[chercheur],
    tasks=[tache],
    memory=True,  # active la memoire long terme (ChromaDB sous le capot)
    embedder={
        "provider": "ollama",
        "config": {"model": "nomic-embed-text"},
    },
)

#任务计划

规划能力是指智能体将复杂目标分解为有序步骤后再采取行动的能力。缺乏此能力，本地模型往往直接执行首个想到的操作，容易迷失方向。存在两种实现方式。

隐式规划（ReAct）

模型逐步明确写出推理过程，选择行动、观察结果，然后重新规划。这种方式容易实现，但用于小模型时不够稳健，因为它们在几轮交互后就容易丢失思路。

显式规划

一个专门负责规划的智能体（或第一项任务）生成步骤列表，随后由执行智能体处理这些步骤。这种方式在本地运行时更稳健：将“思考”与“执行”分开，减轻每次调用的负担。

分层分解

对于耗时较长的任务，CrewAI 支持分层流程，由一个“管理者”智能体委派任务并进行监督。这种方式很强大，但应留给确有需要的场景——协调会消耗 token。

本地使用准则：模型越小，计划越需明确，每一步的范围也应越小。一个处理明确微任务的14B模型，比一个32B模型盲目应对模糊目标更可靠。

#数据安全

本地化执行消除了向第三方API泄露数据的风险，但自主代理会引入自身风险：它会基于生成的文本执行操作，有时甚至会造成破坏。隐私保护并不意味着可以缺少安全防护机制。

最小权限原则

只给智能体提供必不可少的工具。不需要写入磁盘的智能体就不应配备写入工具——这是防止造成损害的第一道防线。

对敏感操作进行人工审核

对于所有不可逆操作（删除、发送、支付、修改数据库），必须手动确认。完全自主权仅适用于安全且可逆的操作。

代码执行隔离

如果智能体执行代码，请让它在容器或沙箱环境中执行，绝不要直接在宿主机上运行。藏在文档中的恶意提示词可能劫持智能体的行为（提示词注入）。

操作日志记录

记录每一次工具调用和每一项决策。如果出现意外行为，这些记录是您了解智能体实际做了什么的唯一途径。

#技巧与故障排除

智能体陷入循环，始终无法停止

请检查停止条件和迭代次数上限。通常是目标过于模糊，或智能体没有意识到自己已经完成任务：请在提示词中明确说明预期结果。

格式错误的工具调用

模型会编造参数或遗漏字段。请简化工具的结构定义，将量化精度提高一级（Q4 → Q5），或换用工具调用更可靠的模型。

多智能体环境下的响应缓慢

每个智能体都需要一次完整的模型调用。本地运行时，请减少智能体数量、缩短系统提示词，并确认模型能完全装入显存，否则 CPU 卸载会导致吞吐量大幅下降。

记忆模块检索不到任何相关内容

嵌入模型选择不当，或分块过大、过小。请确认 Ollama 的嵌入服务正在运行，并调整已存储文本块的大小。

连接 :11434 端口被拒绝

Ollama 未启动，或正在另一个网络接口上监听。请使用“curl http://localhost:11434/api/tags”确认，并检查传递给框架的 base_url。

#深入了解

本指南介绍整体架构；以下教程则深入讲解各个组件的具体实现：

使用 CrewAI 实现多智能体

《CrewAI + Ollama：在本地编排多个 AI 智能体》详细介绍了如何组建一支专业智能体团队，并说明各自的角色和任务。

用 Python 从头到尾构建一个智能体

《使用 LangChain 和 Ollama 在 Python 中创建本地 AI 智能体》一步步构建一个能够调用工具并读取文件的智能体。

记忆模块（RAG）

《使用 ChromaDB 和 Ollama 实现本地 RAG：Python 教程》涵盖了嵌入 → 检索 → 回答的完整流程，这也是长期记忆的核心。