本地AI Agent Hello World(Python版): Ollama + LangChain 快速上手指南

liftword4周前 (05-23)技术文章6

概要

本文将用最简洁的 Python 示例（后续还会推出 Java 版本），带你逐步完成本地大模型 Agent 的“Hello World”：

1、介绍核心工具组件：Ollama、LangChain 和 LangServe；

2、进行环境安装；

3、通过一段完整的 Python 代码示例，实现本地启动、调用大模型，并构建你的第一个本地 AI Agent 智能体。

在动手之前，不妨先了解一下本地构建 AI Agent 的四大优势：

数据本地留存：全程无需外发，杜绝传输泄露风险；

合规与隐私：满足 GDPR、HIPAA 等严格法规对数据本地化的要求；

独立可控：摆脱在线服务的策略调整与网络波动影响；

机密保护：关键研发与商业数据绝不外泄，最大程度保全知识产权。

接下来，我们将直接进入核心组件的介绍与实操讲解，让你在最短时间内完成本地 AI Agent 的“Hello World”的搭建。

Ollama

客户端 (Client) 与服务端 (Server) 分离

Ollama 采用经典的前后端分离架构：客户端（CLI 或 SDK）负责向用户暴露命令与接口，服务端（用 Go 实现的 ollama-http-server）则提供 REST API，二者通过本机 HTTP 通信完成指令下发与结果回传。

Modelfile：模型与配置的一体化

1、Modelfile 将模型权重、tokenizer、系统提示（system prompt）及运行参数打包在同一个目录或文件中，类似于 Docker 镜像的概念，一次 ollama pull <model> 即可获取全部所需资源。

2、通过 ollama show <model> 可以快速查看 Modelfile 的元数据信息，如模型大小、license、支持的硬件加速等。

推理引擎与硬件加速

1、Ollama 内部集成了高效的推理后端（如 llama.cpp），支持 CPU 多线程与 GPU CUDA 加速，能够在无 GPU 的设备（例如 Raspberry Pi）上也执行基本推理。

2、用户可在 Modelfile 中指定 device: gpu 或通过环境变量控制并发线程数，以达到性能与资源利用的最佳平衡。

LangChain

核心接口与模块划分

LangChain 将 LLM 应用拆分为若干可组合的接口与模块，包括：

1、Models：封装各种 LLM 提供者（本地 Ollama、OpenAI、Anthropic 等）的统一调用接口。

2、Prompts：定义 Prompt 模板与变量注入规则，简化大规模 Prompt 管理。

3、Chains：可串联的执行单元，将多个调用（如检索→生成→解析）组成流水线。

4、Tools：第三方 API、脚本或自定义函数的抽象化，可由 Agent 动态调度。

5、Agents：具备“感知—决策—执行”循环的智能体，自动选择适当 Tools 处理复杂任务。

多样化存储与记忆（Memory & Indexes）

1、Memory：提供对话历史、检索结果等上下文的持久化方案，支持短期（会话级）和长期（文件级）记忆管理。

2、Indexes/Vector Stores：结合向量检索框架（如 FAISS、Weaviate）实现 RAG（Retrieval-Augmented Generation），将外部文档作为 Prompt 源增强回答准确性。

LangServe(LangChain-Serve）

快速部署为 REST API

LangServe（即 langchain-serve）基于 FastAPI，使用简单的装饰器（@serve.serving）即可将任意 Chain、Agent 或 Runnable 暴露为 HTTP 接口，并自动生成 OpenAPI 文档。

丰富的服务特性

1、流式输出 (Streaming)：支持将模型生成的 Token 实时推送给客户端，适合对话与写作助手场景。

2、批量处理 (Batching)：一次性接受多条请求，合并推理以提升吞吐量，降低网络与计算开销。

3、多并发支持：基于 Uvicorn/Gunicorn 实现多进程、异步 I/O，轻松应对高并发访问。

与 Ollama & LangChain 无缝集成

1、在 LangServe 中，只需将 ollama.llm("模型名") 得到的 LLMChain 作为 Runnable 注入，即可直接通过 HTTP 端点调用本地 Ollama 服务。

2、完全兼容 LangChain 的所有工具与 Memory，使得原型与生产环境部署之间零改动。

环境安装

硬件与系统要求

1、操作系统：macOS、Linux（Ubuntu/Debian）或 Windows Subsystem for Linux（WSL）均可。

2、硬件：建议至少 8 GB 内存，若要较流畅地运行 7B 以上级别模型，需配备 NVIDIA/AMD GPU（安装对应驱动）或 Apple Silicon 芯片。

安装 Ollama

命令行安装

1、Linux / macOS：curl -fsSL
https://ollama.com/install.sh | sh

2、macOS：也可通过 brew install ollama 安装

3、Windows (PowerShell)：iwr
https://ollama.com/install.ps1 -useb | iex

官网下载安装

官网地址：
https://ollama.com/download

根据系统自行选择下载安装即可。

安装成功检验

在终端里面输入：ollama serve

在浏览器例如输入：http://127.0.0.1:11434，出现“Ollama is running”说明安装成功。

安装本地大模型

在 https://ollama.com/search 里面找到自己需要的大模型，我本地安装了 qwen3:1.7b 和 deepseek-r1:8b。使用命令 ollama pull qwen3:1.7b 安装；

安装完后，可以通过 ollama list 查看本地安装的大模型。

Python及依赖安装

示例代码通过miniconda来做Python环境隔离，poetry来做依赖管理。miniconda安装参考：
https://docs.anaconda.net.cn/miniconda/install/。

下载对应代码示例：
https://github.com/joyang1/AI_Agent_Py_Demos，切换到示例代码根目录，按下述不走运行：

1、创建conda隔离环境：conda create -n py12 python=3.12

2、激活conda环境：conda activate py12

3、在conda环境里面安装poetry：pip install poetry

4、安装依赖：poetry install

代码运行

CLI代码运行

from langchain_ollama.llms import OllamaLLM

class CustomChatAgentCLi(object):
    @property
    def _llm_type(self) -> str:
        # 返回我们自定义的模型标记
        return "qwen3-1.7b"

    def __init__(self):
        self.llm = OllamaLLM(base_url="http://127.0.0.1:11434", model="deepseek-r1:8b")

    def llama_completion(self, user_input) -> str:
        # 调用llama的接口，返回响应
        # return "Hello from llama!"
        try:
            response = self.llm.invoke(user_input)
            return response
        except Exception as e:
            print(f"error:{e}")
        return "error"

llm = CustomChatAgentCLi()
print(llm.llama_completion("你是谁？"))

结合LangServe通过UI运行

然后在浏览器输入：
http://localhost:8000/writer/playground/

出现如下页面说明启动UI启动成功。

我本地的AI Agent是一个专注于前沿技术(大模型)知识分享的博主。你可以输入任意的主题，让它帮你写一篇 markdown 格式的博文。

下面你可以输入对应的主题进行，比如我输入：大模型从0到1入门。输出如下：

流照教程网