PERSONAL LEARNING GUIDE

基于 Ollama 的
AI 开发入门指南

在本地运行开源模型，从零开始学习 AI 应用开发

STEP 01

安装与配置 Ollama

安装 Ollama
BASH — macOS / Linux 
# 一键安装
curl -fsSL https://ollama.com/install.sh | sh

# Windows：直接下载安装包
# https://ollama.com/download
拉取并运行第一个模型
BASH 
# 拉取模型（首次会下载权重文件）
ollama pull llama3.2

# 直接在终端对话
ollama run llama3.2

# 查看已安装的模型
ollama list

# 查看运行状态
ollama ps
验证 API 服务

Ollama 启动后自动在本地开放 HTTP API，默认端口 11434。

BASH 
# 测试 API 是否正常
curl http://localhost:11434/api/generate \
  -d '{
    "model": "llama3.2",
    "prompt": "你好，用一句话介绍自己",
    "stream": false
  }'
提示：如需从其他设备访问，启动时设置 OLLAMA_HOST=0.0.0.0 环境变量即可。
STEP 02

选择合适的模型

根据你的硬件选择模型，显存/内存是主要限制因素。

// 推荐入门模型

llama3.2:3b 2GB RAM · 速度极快 · 适合快速原型 入门首选
llama3.1:8b 5GB RAM · 综合能力均衡 · 日常开发主力 推荐
qwen2.5:7b 5GB RAM · 中文能力优秀 · 中文场景首选 中文优化
qwen2.5-coder:7b 5GB RAM · 代码生成专项 · 编程辅助 代码专项
deepseek-r1:8b 6GB RAM · 推理能力强 · 逻辑/数学场景 推理增强
llama3.1:70b 40GB RAM · 接近 GPT-4 水平 · 需要高端硬件 高端
硬件参考：M1/M2 MacBook 16GB 内存可流畅运行 8B 模型；8GB 独显（RTX 3070 等）也够用；CPU 运行速度较慢但完全可行。

// 模型类型说明

Base Model
原始预训练权重，适合继续微调，不适合直接对话使用。
base
Instruct / Chat Model
经过 SFT + RLHF 对齐，可以直接对话和执行指令，Ollama 默认拉取此类型。
instruct chat
STEP 03

Ollama API 使用

Ollama 提供两套 API：原生 REST API 和 OpenAI 兼容 API（推荐使用）。

// OpenAI 兼容接口（推荐）

与 OpenAI SDK 完全兼容，只需改 base_url，现有代码零改动迁移。

BASH — curl 
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "messages": [
      {"role": "system", "content": "你是一位 Python 专家"},
      {"role": "user",   "content": "写一个快速排序函数"}
    ]
  }'

// 流式输出

BASH 
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "stream": true,
    "messages": [{"role": "user", "content": "讲一个笑话"}]
  }'

// 常用 API 端点

POST /v1/chat/completions 对话补全（OpenAI 兼容，推荐）
POST /v1/embeddings 文本向量化，用于 RAG / 语义搜索
POST /api/generate 原生单轮补全接口
GET /api/tags 列出本地已安装模型
POST /api/pull 拉取模型（编程式）
STEP 04

Python 开发实践

// 环境准备

BASH 
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 安装依赖
pip install openai ollama langchain-ollama

// 方式一：使用 OpenAI SDK（推荐）

PYTHON 
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"  # 填任意字符串即可
)

response = client.chat.completions.create(
    model="qwen2.5:7b",
    messages=[
        {"role": "system", "content": "你是一位专业的代码助手"},
        {"role": "user",   "content": "用 Python 实现一个简单的 HTTP 服务器"},
    ],
)

print(response.choices[0].message.content)

// 方式二：使用 Ollama 官方 SDK

PYTHON 
import ollama

# 流式对话
for chunk in ollama.chat(
    model="llama3.2",
    messages=[{"role": "user", "content": "解释什么是 Transformer"}],
    stream=True,
):
    print(chunk["message"]["content"], end="", flush=True)

# 生成 Embeddings
result = ollama.embed(model="nomic-embed-text", input="这是一段示例文本")
vector = result["embeddings"][0]  # 768 维向量

// 多轮对话管理

PYTHON 
from openai import OpenAI

class ChatBot:
    def __init__(self, model="qwen2.5:7b", system=""):
        self.client = OpenAI(base_url="http://localhost:11434/v1", api_key="x")
        self.model = model
        self.history = [{"role": "system", "content": system}] if system else []

    def chat(self, user_input):
        self.history.append({"role": "user", "content": user_input})
        resp = self.client.chat.completions.create(
            model=self.model, messages=self.history
        )
        reply = resp.choices[0].message.content
        self.history.append({"role": "assistant", "content": reply})
        return reply

# 使用示例
bot = ChatBot(system="你是一位耐心的编程导师，用简洁的方式解释概念")
print(bot.chat("什么是向量数据库？"))
print(bot.chat("它和普通数据库的区别是什么？"))
STEP 05

构建 RAG 应用

检索增强生成（RAG）是最实用的 AI 应用模式，让模型能够查阅你自己的文档。

// 安装依赖

BASH 
pip install chromadb langchain-ollama langchain-community pypdf

// 拉取 Embedding 模型

BASH 
# nomic-embed-text 是 Ollama 上最常用的 embedding 模型
ollama pull nomic-embed-text

// 完整 RAG 示例

PYTHON 
from langchain_ollama import OllamaEmbeddings, ChatOllama
from langchain_community.vectorstores import Chroma
from langchain_community.document_loaders import TextLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter

# 1. 加载文档并切片
loader = TextLoader("my_docs.txt", encoding="utf-8")
splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
docs = splitter.split_documents(loader.load())

# 2. 向量化并存入 ChromaDB
embeddings = OllamaEmbeddings(model="nomic-embed-text")
vectorstore = Chroma.from_documents(docs, embeddings)
retriever = vectorstore.as_retriever(search_kwargs={"k": 3})

# 3. 检索 + 生成
def ask(question):
    context = "\n\n".join([d.page_content for d in retriever.invoke(question)])
    llm = ChatOllama(model="qwen2.5:7b")
    prompt = f"根据以下资料回答问题：\n\n{context}\n\n问题：{question}"
    return llm.invoke(prompt).content

print(ask("文档里提到了哪些核心概念？"))
提示：RAG 的质量主要取决于切片策略和检索精度，建议 chunk_size 在 300~800 之间调试，chunk_overlap 保持 chunk_size 的 10% 左右。
STEP 06

构建 AI Agent

Agent 让模型能够使用工具、调用函数，完成多步骤复杂任务。

// Function Calling 示例

PYTHON 
import json
from openai import OpenAI

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

# 定义工具
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气信息",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名称"}
            },
            "required": ["city"]
        }
    }
}]

# 工具实现
def get_weather(city):
    return {"city": city, "temp": "22°C", "condition": "晴"}

# Agent 循环
messages = [{"role": "user", "content": "北京今天天气怎么样？"}]

resp = client.chat.completions.create(
    model="llama3.1:8b", messages=messages, tools=tools
)
msg = resp.choices[0].message

if msg.tool_calls:
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        result = get_weather(**args)
        messages += [
            msg,
            {"role": "tool", "tool_call_id": call.id,
             "content": json.dumps(result, ensure_ascii=False)}
        ]
    final = client.chat.completions.create(
        model="llama3.1:8b", messages=messages
    )
    print(final.choices[0].message.content)
注意：Function Calling 能力因模型而异，llama3.1、qwen2.5 支持较好；小于 7B 的模型工具调用稳定性较差。
LEARNING PATH

推荐学习路径

PHASE 01
跑通基础
第 1–2 周
PHASE 02
API 开发
第 3–4 周
PHASE 03
RAG 应用
第 5–7 周
PHASE 04
Agent 开发
第 8–10 周
PHASE 05
微调部署
第 11 周+
阶段 1 目标
安装 Ollama，跑通第一个模型对话；理解 Base / Instruct / Chat 模型的区别；会用 curl 调用 API。
阶段 2 目标
用 Python + OpenAI SDK 写多轮对话；理解 system prompt 的作用；实现流式输出。
阶段 3 目标
理解 Embedding 和向量数据库；用 LangChain 构建文档问答 RAG；体验 nomic-embed-text。
阶段 4 目标
实现 Function Calling；用 LangGraph 或 CrewAI 构建多步骤 Agent；了解 ReAct 模式。

// 推荐工具栈

Ollama 本地模型运行时，提供 OpenAI 兼容 API
LangChain RAG / Chain / Agent 构建框架，生态最完整
ChromaDB 轻量级本地向量数据库，零配置启动
LangGraph 状态机式 Agent 编排，适合复杂多步骤流程
Streamlit / Gradio 快速搭建演示 UI，无需前端经验
Open WebUI Ollama 的本地 ChatGPT 界面，docker 一键部署
Open WebUI 快速启动：
docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway ghcr.io/open-webui/open-webui:main
访问 http://localhost:3000 即可获得完整的 Chat UI，支持所有 Ollama 模型。