1. 环境准备与基础概念

如果你对在本地运行大语言模型感兴趣，但又觉得配置复杂、命令繁琐，那Ollama绝对是你的“梦中情工具”。简单来说，Ollama是一个开源的框架，它把大模型的下载、运行和管理都打包成了极其简单的命令。你不需要去研究复杂的Python环境、CUDA版本或者模型权重文件，只需要几条命令，就能让Llama 3、Mistral这些明星模型在你的电脑上跑起来。而Ollama API，就是打开这个宝藏的钥匙，它允许你通过标准的HTTP请求，用代码来指挥这些模型干活，无论是构建一个智能对话应用，还是开发一个文本分析工具，都变得轻而易举。

我刚开始接触本地大模型时，被各种依赖和配置搞得头大，直到用了Ollama，感觉就像从手动挡换成了自动挡。它的核心设计理念就是“开箱即用”。你只需要去官网根据你的操作系统（Windows、macOS、Linux）下载对应的安装包，一路点击“下一步”就能完成安装。安装完成后，一个后台服务（我们通常称之为ollama serve）就已经在运行了，它默认监听本地的11434端口，这就是我们所有API调用的入口。

在深入API之前，我们先明确几个关键概念，这能帮你更好地理解后续的操作。首先是“模型”，在Ollama的语境里，一个模型就是一个可以执行特定任务（如对话、文本生成）的AI程序包，比如llama3:8b代表Meta发布的80亿参数版本的Llama 3模型。Ollama维护了一个丰富的模型库，你可以把它想象成一个应用商店。其次是“Modelfile”，这是Ollama用来定义和定制模型的配置文件，你可以基于一个已有的模型，通过Modelfile注入系统指令、调整参数，创造出属于你自己的专属模型变体。最后是“上下文”，这相当于模型的“短期记忆”。在多轮对话中，你需要将上一轮API返回的上下文ID传递给下一轮请求，模型才能记住之前的对话内容，实现连贯的交流。

准备好这些基础知识后，我们就可以挽起袖子，开始真正的实战了。接下来的内容，我会带你从最基础的模型管理开始，一步步深入到智能对话开发，过程中我会分享很多我实际踩过的坑和总结出来的最佳实践，保证你能跟着做下来，并且立刻用到自己的项目里。

2. 模型管理全攻略：你的私人模型仓库

管理模型是使用Ollama的第一步，也是最常做的操作。你可以把Ollama想象成你的私人模型管家，而API就是你给管家下达指令的对讲机。这一部分，我们会详细拆解如何查看、下载、删除和定制模型。

2.1 查看与拉取：掌握模型清单

安装好Ollama后，你可能会好奇：“我现在本地到底有哪些模型？” 这时候就要用到列出模型的API了。这个操作非常简单，用一个GET请求就能搞定。你可以在终端里直接用curl命令，也可以在Python脚本中用requests库。我个人的习惯是先用curl快速测试一下服务是否正常，然后在正式项目里用Python。

curl http://localhost:11434/api/tags

如果一切正常，你会收到一个JSON格式的响应，里面包含了所有已下载模型的详细信息，比如模型名字、大小、修改日期等。用Python写的话，代码也很直观：

import requests

response = requests.get("http://localhost:11434/api/tags")
if response.status_code == 200:
    models = response.json().get("models", [])
    for model in models:
        print(f"模型名: {model['name']}")
        print(f"大小: {model.get('size', 'N/A')}")
        print(f"修改时间: {model.get('modified_at', 'N/A')}")
        print("-" * 20)
else:
    print(f"请求失败，状态码: {response.status_code}")

当你看到本地模型列表空空如也，或者想尝试一个新模型时，就需要“拉取”模型。拉取其实就是从Ollama的官方仓库下载模型文件到本地。这里有个小技巧：Ollama支持流式拉取，这意味着你可以在终端实时看到下载进度条，对于几个G的大模型来说，这个反馈非常贴心。拉取模型的API是/api/pull，需要以POST方式发送一个包含模型名称的JSON数据。

# 拉取 Mistral 7B 模型，并流式显示进度
curl http://localhost:11434/api/pull -d '{"name": "mistral"}'

# 如果你想安静地拉取，不显示进度流，可以设置 stream 为 false
curl http://localhost:11434/api/pull -d '{"name": "llama3:8b", "stream": false}'

在Python中，我建议对于大型模型使用流式拉取，这样你可以在代码中处理进度信息，给用户更好的体验。

import requests
import json

def pull_model_with_progress(model_name: str):
    """带进度显示的模型拉取函数"""
    url = "http://localhost:11434/api/pull"
    data = {"name": model_name, "stream": True}

    with requests.post(url, json=data, stream=True) as response:
        for line in response.iter_lines():
            if line:
                try:
                    chunk = json.loads(line)
                    # 拉取状态信息
                    status = chunk.get("status", "")
                    if "digest" in status:
                        print(f"[下载摘要] {chunk.get('digest', '')}")
                    elif "pulling" in status:
                        layer = chunk.get("id", "")
                        print(f"[下载层] {layer} - {status}")
                    elif "verifying" in status:
                        print("[校验文件完整性...]")
                    elif status == "success":
                        print(f"[成功] 模型 '{model_name}' 已拉取完成！")
                except json.JSONDecodeError:
                    print(f"收到非JSON响应: {line}")

# 使用示例
pull_model_with_progress("codellama:7b")

2.2 删除与定制：精细化模型管理

随着你尝试的模型越来越多，磁盘空间可能会告急。这时候，删除不再需要的模型就很重要了。删除操作通过/api/delete端点完成，这是一个DELETE请求。操作前一定要确认模型名称，因为删除是不可逆的。我有个血泪教训：曾经不小心把训练了好几天的自定义模型给删了，所以现在执行删除前我都会先列出来双重确认。

import requests

def delete_model(model_name: str):
    """删除指定模型"""
    url = "http://localhost:11434/api/delete"
    response = requests.delete(url, json={"name": model_name})
    
    if response.status_code == 200:
        print(f"模型 '{model_name}' 已成功删除。")
    else:
        error_msg = response.json().get("error", "未知错误")
        print(f"删除失败: {error_msg}")

# 使用前请务必确认！
# delete_model("llama2:13b")

Ollama最强大的功能之一，是允许你创建自定义模型。你不需要从头训练一个模型，而是可以基于一个现有的优秀模型（比如llama3），通过编写一个Modelfile来注入你的特定指令和配置，生成一个专属于你任务的模型。这就像给一个博学的学者一份详细的工作说明书。创建自定义模型使用/api/create端点。

举个例子，我想创建一个专门用于代码审查的助手。我可以基于codellama模型，给它设定一个系统角色。

import requests

modelfile_content = """
FROM codellama:7b
# 设定系统指令，定义模型的行为
SYSTEM 你是一个资深代码审查专家，擅长Python和JavaScript。你的任务是仔细检查用户提供的代码，指出潜在的性能问题、安全漏洞、代码风格不符合PEP 8或ESLint规范的地方，并提供具体的修改建议。语气要专业且友好。
# 可以设置一些模型参数
PARAMETER temperature 0.3  # 降低随机性，让回答更确定、专业
PARAMETER num_ctx 4096     # 设置上下文窗口
"""

def create_custom_model():
    url = "http://localhost:11434/api/create"
    payload = {
        "name": "my-code-reviewer",
        "modelfile": modelfile_content
    }
    
    response = requests.post(url, json=payload)
    if response.status_code == 200:
        print("自定义模型 'my-code-reviewer' 创建成功！")
        # 创建成功后，就可以像使用其他模型一样使用它了
        # generate_text("my-code-reviewer", "请审查这段代码：def foo(x): return x*2")
    else:
        print(f"创建失败: {response.json()}")

create_custom_model()

通过这种方式，你可以打造出法律顾问、创意写手、学习伙伴等各种垂直领域的专用AI助手，而无需关心底层复杂的模型微调过程。

3. 核心交互：文本生成与智能对话

模型准备就绪后，我们就可以进入最激动人心的部分：让模型动起来，生成文本和进行对话。Ollama提供了两个核心端点来完成这些任务：/api/generate用于单轮文本补全或生成，/api/chat用于更结构化的多轮对话。理解两者的区别和适用场景，能让你在开发中事半功倍。

3.1 单轮文本生成：简单直接的力量

/api/generate端点是最基础的文本交互接口。你给它一个提示（prompt），它返回模型生成的续写内容。它非常适合一些不需要复杂上下文记忆的任务，比如：翻译一句话、总结一段文本、写一个函数、生成一些创意想法等。它的请求体结构相对直接，但包含了许多控制生成质量的关键参数。

让我们来看一个完整的Python示例，并详细解释每个参数的作用：

import requests
import json

def generate_text(model: str, prompt: str, system_prompt: str = None, use_stream: bool = False):
    """
    使用 /api/generate 生成文本
    
    Args:
        model: 模型名称，如 'llama3:8b'
        prompt: 给模型的输入提示
        system_prompt: 可选的系统指令，用于设定模型角色
        use_stream: 是否使用流式输出（适合长文本，体验更好）
    """
    url = "http://localhost:11434/api/generate"
    
    # 构建请求数据
    data = {
        "model": model,
        "prompt": prompt,
        "stream": use_stream,
        "options": {
            "temperature": 0.7,      # 温度：控制随机性。0.0最确定，1.0更多样。创意写作可调高，代码生成宜调低。
            "top_p": 0.9,            # 核采样：与温度配合，控制候选词范围。通常0.8-0.95。
            "max_tokens": 512,        # 生成的最大token数。注意：token不等于单词，一个词可能被分成多个token。
            "num_ctx": 2048,          # 上下文窗口大小。模型能看到的prompt+生成的总token上限。
            "repeat_penalty": 1.1     # 重复惩罚：大于1.0会降低重复词的概率，抑制车轱辘话。
        }
    }
    
    # 添加可选的系统提示
    if system_prompt:
        data["system"] = system_prompt
    
    if use_stream:
        # 流式处理
        response = requests.post(url, json=data, stream=True)
        full_response = ""
        for line in response.iter_lines():
            if line:
                try:
                    chunk = json.loads(line)
                    chunk_text = chunk.get("response", "")
                    print(chunk_text, end="", flush=True)  # 逐块打印，实现打字机效果
                    full_response += chunk_text
                    if chunk.get("done", False):
                        # 生成完成，返回最终的上下文（用于后续延续）
                        final_context = chunk.get("context", [])
                        print(f"\n[生成完成]")
                        return full_response, final_context
                except json.JSONDecodeError:
                    print(f"流式响应解析错误: {line}")
    else:
        # 非流式，一次性返回
        response = requests.post(url, json=data)
        if response.status_code == 200:
            result = response.json()
            print(result.get("response"))
            return result.get("response"), result.get("context", [])
        else:
            print(f"请求失败: {response.status_code}, {response.text}")
            return None, None

# 示例1：简单的文本补全
response, ctx = generate_text("llama3:8b", "法国的首都是")
print(f"回答: {response}")

# 示例2：带系统指令的创意写作
creative_response, _ = generate_text(
    model="mistral",
    prompt="写一个关于机器人和猫咪的温馨故事开头：",
    system_prompt="你是一个充满想象力的儿童文学作家，擅长创作温暖有趣的小故事。",
    use_stream=True  # 开启流式，看它一个字一个字“创作”
)

参数调优心得：temperature是我调整最多的参数。写邮件、生成代码时，我会设到0.2-0.4，让输出更稳定可靠；写诗、头脑风暴时，会调到0.8-1.0，激发更多可能性。max_tokens要小心设置，设得太小回答可能被截断，设得太大如果模型“跑偏”了会生成一堆无意义内容。我通常先设一个保守值（如256），根据输出情况再调整。

3.2 多轮对话：构建有记忆的聊天机器人

虽然/api/generate通过传递context也能实现多轮对话，但/api/chat端点是专门为对话场景设计的，它使用了更符合业界标准的messages列表格式（类似OpenAI的API），结构更清晰，管理对话历史更方便。每个message都是一个字典，包含role（角色，如user、assistant、system）和content（内容）。

/api/chat接口会自动帮你管理对话上下文，你只需要把整个对话历史列表传给它就行。这对于开发聊天机器人、客服助手等应用来说，代码会简洁很多。

def chat_with_model(model: str, message_history: list, use_stream: bool = False):
    """
    使用 /api/chat 进行多轮对话
    
    Args:
        model: 模型名称
        message_history: 消息历史列表，格式为 [{"role": "user", "content": "..."}, ...]
                        通常以 system 消息开头（可选），然后是交替的 user 和 assistant 消息。
        use_stream: 是否流式输出
    """
    url = "http://localhost:11434/api/chat"
    
    data = {
        "model": model,
        "messages": message_history,
        "stream": use_stream,
        "options": {
            "temperature": 0.8,
            "num_ctx": 4096  # 对话可能需要更长的上下文
        }
    }
    
    if use_stream:
        response = requests.post(url, json=data, stream=True)
        full_reply = ""
        for line in response.iter_lines():
            if line:
                try:
                    chunk = json.loads(line)
                    # 注意：chat流式响应中，内容在 `message` 字段里
                    message_chunk = chunk.get("message", {})
                    if message_chunk:
                        content = message_chunk.get("content", "")
                        print(content, end="", flush=True)
                        full_reply += content
                    if chunk.get("done", False):
                        print()  # 换行
                        # 对话完成后，你可以选择将助手的回复追加到历史中，以便下次继续
                        new_history = message_history + [{"role": "assistant", "content": full_reply}]
                        return full_reply, new_history
                except json.JSONDecodeError:
                    print(f"流式响应解析错误: {line}")
        return full_reply, message_history
    else:
        response = requests.post(url, json=data)
        if response.status_code == 200:
            result = response.json()
            assistant_reply = result["message"]["content"]
            print(f"助手: {assistant_reply}")
            # 更新对话历史
            updated_history = message_history + [{"role": "assistant", "content": assistant_reply}]
            return assistant_reply, updated_history
        else:
            print(f"对话失败: {response.status_code}")
            return None, message_history

# 示例：模拟一个简单的多轮对话
conversation_history = [
    {"role": "system", "content": "你是一个乐于助人且知识渊博的图书馆管理员。"},
    {"role": "user", "content": "你好，能推荐一些科幻小说吗？"},
]

# 第一轮
reply, conversation_history = chat_with_model("llama3", conversation_history, use_stream=True)
# 用户接着问
conversation_history.append({"role": "user", "content": "这些书里，哪一本最适合科幻入门者阅读呢？"})
# 第二轮，模型能记得之前推荐过的书
reply, conversation_history = chat_with_model("llama3", conversation_history, use_stream=True)

在实际项目中，你需要维护这个message_history列表。需要注意的是，上下文长度（num_ctx）是有限的（比如4096个token）。当对话轮数很多，历史消息总长度超过这个限制时，模型就会“忘记”最早的内容。常见的处理策略是只保留最近N轮对话，或者当历史过长时，尝试用模型去总结之前的对话内容，然后将总结作为新的系统提示，从而节省token。

4. 高级应用与性能调优

掌握了基本交互后，我们可以玩点更高级的，并让模型运行得更高效。Ollama API不仅提供了文本生成和对话，还隐藏着一些非常实用的高级功能，比如生成文本的嵌入向量，这对于构建搜索、聚类等应用至关重要。同时，正确地调优参数能显著提升生成速度和质量。

4.1 生成嵌入向量：解锁语义理解

嵌入（Embedding）是将一段文本（一个词、一句话或一个段落）转换成一系列数字（即向量）的过程。这个向量包含了文本的语义信息。语义相似的文本，其向量在空间中的距离也更近。Ollama的/api/embeddings端点可以方便地为你使用的模型生成嵌入向量。

这个功能有什么用呢？我举几个我实际用到的例子：

1. 智能搜索：将你的文档库都转换成向量存储起来。当用户搜索时，将搜索词也转换成向量，然后找出向量最相似的文档，这比传统的关键词匹配要智能得多。
2. 文本分类：计算待分类文本与各个类别代表文本向量的相似度，归入最相似的类别。
3. 聚类分析：把大量文本的向量放在一起，用算法自动发现它们之间的聚集模式。

使用起来非常简单：

def get_text_embedding(model: str, text: str):
    """获取文本的嵌入向量"""
    url = "http://localhost:11434/api/embeddings"
    data = {
        "model": model,
        "prompt": text
        # 这里也可以传入 `options` 来调整生成嵌入时的参数，但大多数模型有默认值
    }
    
    response = requests.post(url, json=data)
    if response.status_code == 200:
        embedding_vector = response.json()["embedding"]
        print(f"文本 '{text[:50]}...' 的嵌入向量维度: {len(embedding_vector)}")
        print(f"前5个值: {embedding_vector[:5]}")
        return embedding_vector
    else:
        print(f"获取嵌入失败: {response.status_code}")
        return None

# 示例：比较两个句子的语义相似性（使用简单的余弦相似度）
import numpy as np

def cosine_similarity(vec_a, vec_b):
    """计算两个向量的余弦相似度"""
    dot_product = np.dot(vec_a, vec_b)
    norm_a = np.linalg.norm(vec_a)
    norm_b = np.linalg.norm(vec_b)
    return dot_product / (norm_a * norm_b)

# 生成三个句子的嵌入
sentence1 = "我喜欢吃苹果。"
sentence2 = "苹果是一种美味的水果。"
sentence3 = "我今天买了一台新电脑。"

embedding1 = get_text_embedding("llama3", sentence1)
embedding2 = get_text_embedding("llama3", sentence2)
embedding3 = get_text_embedding("llama3", sentence3)

if embedding1 and embedding2 and embedding3:
    sim_1_2 = cosine_similarity(embedding1, embedding2)
    sim_1_3 = cosine_similarity(embedding1, embedding3)
    print(f"句子1和句子2的语义相似度: {sim_1_2:.4f}")
    print(f"句子1和句子3的语义相似度: {sim_1_3:.4f}")
    # 预期结果：句子1和2（都关于苹果作为水果）的相似度应远高于句子1和3。

4.2 性能调优与参数详解

要让Ollama模型在你的硬件上跑得又快又好，理解并调整options里的参数是关键。这些参数直接影响生成速度、质量和资源消耗。下面我结合自己的经验，详细解读几个核心参数：

• num_ctx (上下文窗口大小)：这是模型一次性能处理的文本长度上限（以token计）。增大它可以让模型记住更长的对话或文档，但代价是消耗更多的内存（通常是显存）。对于日常对话，2048或4096通常足够。如果你需要处理长文档摘要，可能需要尝试8192甚至更大的模型（注意：不是所有模型都支持超长上下文）。重要提示：盲目调大num_ctx是导致内存不足（OOM）错误的最常见原因。务必根据你的硬件能力量力而行。

• num_gpu 和 main_gpu (GPU层数与主GPU)：如果你的系统有NVIDIA GPU并且安装了支持的驱动，可以通过num_gpu指定将模型的多少层放到GPU上运行（加速计算），其余层在CPU上运行。main_gpu用于多卡环境，指定主GPU的索引。实测经验：对于7B或8B参数的模型，将全部层（例如32层）放到一张消费级显卡（如RTX 4060）上，速度会比纯CPU快一个数量级。你可以使用ollama run llama3:8b命令观察启动日志，看模型有多少层被“offloaded”到了GPU。

• temperature (温度)：这是控制生成“创意度”的旋钮。值越低（接近0），模型输出越确定、保守，倾向于选择概率最高的词，适合代码生成、事实问答。值越高（接近1），输出越随机、多样，适合创意写作、头脑风暴。我通常的起手式是0.7，然后根据任务上下调整。

• top_p (核采样)：这是另一种控制多样性的方法，与温度可以配合使用。它从累积概率超过p的最小候选词集合中采样。通常设置为0.8到0.95。一个常见的组合是：temperature=0.8, top_p=0.9。

• repeat_penalty (重复惩罚)：模型有时会陷入循环，不断重复相同的短语。将这个值设置为大于1.0（如1.1或1.2），可以降低已出现token的概率，有效抑制重复。在生成长文本时特别有用。

下面是一个综合调优的示例，假设我们有一个较强的GPU，并且需要生成较长的创意文本：

def optimized_generation(model: str, prompt: str):
    url = "http://localhost:11434/api/generate"
    data = {
        "model": model,
        "prompt": prompt,
        "stream": False,
        "options": {
            "num_ctx": 8192,          # 大上下文，用于生成长文
            "num_gpu": 40,            # 假设模型有40层，全部放到GPU上
            "temperature": 0.85,      # 较高的温度，鼓励创意
            "top_p": 0.92,
            "repeat_penalty": 1.15,   # 较强的重复惩罚
            "num_predict": 1024       # 生成较长的文本（注意：此参数名有时可能是`num_predict`而非`max_tokens`，需参考具体模型文档）
        }
    }
    response = requests.post(url, json=data)
    return response.json()

一个常见的坑：不同模型对options参数的支持程度可能不同。例如，有些较小的或特定版本的模型可能不支持num_gpu参数。最稳妥的方式是查阅对应模型的文档，或者先使用较小的参数值进行测试。

5. 实战：构建一个简单的智能对话服务

理论说再多，不如动手做一个项目。现在，让我们把前面学到的所有知识串联起来，用Ollama API和Python的Flask框架，快速搭建一个本地的智能对话Web服务。这个服务将提供模型选择、多轮对话和简单的历史记录功能。

5.1 后端服务搭建

首先，确保你已经安装了Flask：pip install flask。然后我们创建一个app.py文件。

from flask import Flask, request, jsonify, render_template_string
import requests
import json

app = Flask(__name__)

# 存储不同会话的对话历史（简易版，生产环境应用数据库）
conversation_sessions = {}

# 一个简单的HTML前端界面
HTML_TEMPLATE = """
<!DOCTYPE html>
<html>
<head>
    <title>Ollama 智能对话助手</title>
    <style>
        body { font-family: sans-serif; max-width: 800px; margin: 20px auto; padding: 20px; }
        #chatbox { border: 1px solid #ccc; height: 400px; overflow-y: scroll; padding: 10px; margin-bottom: 10px; }
        .message { margin-bottom: 10px; padding: 8px; border-radius: 5px; }
        .user { background-color: #e3f2fd; text-align: right; }
        .assistant { background-color: #f5f5f5; }
        #inputArea { display: flex; }
        #userInput { flex-grow: 1; padding: 10px; }
        #sendBtn { padding: 10px 20px; }
        select, button { margin: 5px; padding: 8px; }
    </style>
</head>
<body>
    <h2>Ollama 智能对话助手</h2>
    <div>
        <label>选择模型：</label>
        <select id="modelSelect">
            <option value="llama3:8b">Llama 3 8B</option>
            <option value="mistral">Mistral 7B</option>
            <option value="codellama:7b">CodeLlama 7B</option>
        </select>
        <button onclick="newSession()">新建会话</button>
        <button onclick="clearHistory()">清空历史</button>
    </div>
    <div id="chatbox"></div>
    <div id="inputArea">
        <input type="text" id="userInput" placeholder="输入你的消息..." onkeypress="handleKeyPress(event)">
        <button id="sendBtn" onclick="sendMessage()">发送</button>
    </div>

    <script>
        let sessionId = Date.now().toString(); // 简单生成一个会话ID
        let currentModel = 'llama3:8b';

        function addMessage(role, content) {
            const chatbox = document.getElementById('chatbox');
            const msgDiv = document.createElement('div');
            msgDiv.className = `message ${role}`;
            msgDiv.textContent = (role === 'user' ? '你：' : '助手：') + content;
            chatbox.appendChild(msgDiv);
            chatbox.scrollTop = chatbox.scrollHeight;
        }

        async function sendMessage() {
            const input = document.getElementById('userInput');
            const message = input.value.trim();
            if (!message) return;
            
            addMessage('user', message);
            input.value = '';
            
            currentModel = document.getElementById('modelSelect').value;
            
            const response = await fetch('/chat', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    session_id: sessionId,
                    model: currentModel,
                    message: message
                })
            });
            
            const data = await response.json();
            if (data.reply) {
                addMessage('assistant', data.reply);
            } else {
                addMessage('assistant', '抱歉，出错了：' + (data.error || '未知错误'));
            }
        }

        function handleKeyPress(event) {
            if (event.key === 'Enter') {
                sendMessage();
            }
        }

        function newSession() {
            sessionId = Date.now().toString();
            document.getElementById('chatbox').innerHTML = '';
            addMessage('system', '新会话已开始。');
        }

        function clearHistory() {
            fetch('/clear', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({ session_id: sessionId })
            }).then(() => {
                document.getElementById('chatbox').innerHTML = '';
                addMessage('system', '当前会话历史已清空。');
            });
        }

        // 初始化
        addMessage('system', '会话已就绪，请选择模型并开始对话。');
    </script>
</body>
</html>
"""

@app.route('/')
def index():
    """提供前端页面"""
    return render_template_string(HTML_TEMPLATE)

@app.route('/chat', methods=['POST'])
def chat():
    """处理对话请求的后端端点"""
    data = request.json
    session_id = data.get('session_id', 'default')
    model = data.get('model', 'llama3:8b')
    user_message = data.get('message', '')
    
    if not user_message:
        return jsonify({'error': '消息不能为空'}), 400
    
    # 获取或初始化该会话的历史
    if session_id not in conversation_sessions:
        conversation_sessions[session_id] = []
    
    history = conversation_sessions[session_id]
    
    # 将用户新消息加入历史
    history.append({"role": "user", "content": user_message})
    
    # 准备请求Ollama API的数据
    ollama_url = "http://localhost:11434/api/chat"
    payload = {
        "model": model,
        "messages": history,
        "stream": False,
        "options": {
            "temperature": 0.8,
            "num_ctx": 4096
        }
    }
    
    try:
        response = requests.post(ollama_url, json=payload, timeout=60)
        if response.status_code == 200:
            result = response.json()
            assistant_reply = result["message"]["content"]
            # 将助手回复加入历史
            history.append({"role": "assistant", "content": assistant_reply})
            # 简单限制历史长度，防止无限增长（例如只保留最近10轮对话）
            if len(history) > 20:  # 10轮对话，每轮user+assistant两条消息
                conversation_sessions[session_id] = history[-20:]
            else:
                conversation_sessions[session_id] = history
                
            return jsonify({'reply': assistant_reply})
        else:
            # 从历史中移除失败的用户消息
            history.pop()
            return jsonify({'error': f'Ollama API错误: {response.status_code}', 'detail': response.text}), 500
    except requests.exceptions.RequestException as e:
        history.pop()
        return jsonify({'error': '连接Ollama服务失败', 'detail': str(e)}), 503

@app.route('/clear', methods=['POST'])
def clear_history():
    """清空指定会话的历史"""
    data = request.json
    session_id = data.get('session_id', 'default')
    if session_id in conversation_sessions:
        conversation_sessions[session_id] = []
    return jsonify({'status': 'cleared'})

if __name__ == '__main__':
    # 在本地启动服务，默认端口5000
    app.run(host='0.0.0.0', port=5000, debug=True)

5.2 运行与扩展

保存好app.py后，在终端运行python app.py。然后在浏览器中打开http://localhost:5000，你就能看到一个简易的聊天界面了。选择模型，输入问题，就能和本地的AI模型对话了。

这个示例虽然简单，但已经具备了核心功能。你可以在此基础上进行大量扩展：

1. 模型管理界面：增加一个下拉框，动态从/api/tags获取本地模型列表。
2. 参数实时调整：在界面上增加滑动条，让用户可以动态调整temperature、max_tokens等参数。
3. 对话持久化：将conversation_sessions从内存字典换成SQLite或Redis数据库，这样重启服务后对话历史不会丢失。
4. 流式输出支持：修改后端/chat接口，支持Server-Sent Events (SSE) 将Ollama的流式响应实时推送到前端，实现打字机效果。
5. 嵌入搜索功能：增加一个文件上传区域，上传文档后自动生成嵌入向量并存入向量数据库（如Chroma），然后增加一个“基于知识库问答”的模式。

我在实际开发中，通常会在项目根目录下创建一个config.yaml文件，用来配置Ollama服务的地址（如果你部署在别的机器上）、默认模型、各种超时时间等，这样代码会更清晰，也便于部署。

6. 错误处理与最佳实践

在开发和实际使用中，遇到错误是家常便饭。良好的错误处理机制和遵循一些最佳实践，能让你和你的应用更加从容。

6.1 常见的错误与应对

Ollama API使用标准的HTTP状态码，结合JSON格式的错误信息。

• 400 Bad Request：这是最常见的错误，通常是请求参数有问题。比如model字段拼写错误（写成了llama3而不是llama3:8b），或者JSON格式不正确。应对：仔细检查请求体，特别是模型名和参数格式。可以用json.dumps(data, indent=2)打印出来看看。

• 404 Not Found：请求的端点不存在，或者模型不存在。如果你刚拉取模型，可能模型文件还没完全准备好，稍等几秒再试。应对：先用/api/tags确认模型是否已成功下载并列出。

• 500 Internal Server Error：服务器内部错误。这可能是Ollama服务本身出了问题，或者你的请求触发了模型的某个bug。应对：首先检查Ollama服务是否在运行（ollama serve）。查看Ollama的日志（通常在终端或系统日志中）获取更详细的错误信息。有时候降低num_ctx或num_gpu的值可以解决内存不足导致的500错误。

• 连接失败/超时：无法连接到localhost:11434。应对：确认Ollama是否已安装并启动。在Windows上，检查Ollama Desktop是否在运行；在macOS/Linux上，在终端运行ollama serve并确保没有报错。

在你的代码中，务必要对API调用进行try-except包装，并给用户友好的提示。

import requests
import time

def robust_ollama_request(url, data, max_retries=3):
    """一个健壮的Ollama请求函数，包含重试机制"""
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=data, timeout=60)
            response.raise_for_status()  # 如果状态码不是200，抛出HTTPError
            return response.json()
        except requests.exceptions.ConnectionError:
            print(f"连接失败，第{attempt+1}次重试...")
            time.sleep(2 ** attempt)  # 指数退避
        except requests.exceptions.Timeout:
            print(f"请求超时，第{attempt+1}次重试...")
            time.sleep(2)
        except requests.exceptions.HTTPError as e:
            # HTTP错误（如400，404，500）通常重试无用，直接返回错误
            error_detail = ""
            try:
                error_detail = response.json().get("error", "")
            except:
                pass
            print(f"HTTP错误 {response.status_code}: {error_detail}")
            return {"error": f"HTTP {response.status_code}", "detail": error_detail}
        except Exception as e:
            print(f"未知错误: {e}")
            return {"error": "Unknown error", "detail": str(e)}
    print(f"请求失败，已达最大重试次数{max_retries}")
    return {"error": "Max retries exceeded"}

6.2 开发与部署建议

根据我多年的项目经验，以下几点建议能帮你少走很多弯路：

1. 从轻量模型开始：如果你是第一次接触，或者硬件资源有限，强烈建议从llama3:8b或mistral:7b这样的7B/8B参数模型开始。它们对硬件要求相对友好（8GB以上内存即可尝试），响应速度也更快，适合学习和原型开发。

2. 注意上下文长度限制：这是最容易引发问题的点。模型有固定的上下文窗口（如4096 tokens）。你的系统提示词、用户问题、历史对话和模型回答的总长度不能超过这个限制。在构建多轮对话应用时，一定要实现历史消息的截断或总结逻辑。

3. 流式传输提升体验：对于任何需要等待模型生成结果的场景，务必使用stream=True。这能让用户几乎实时地看到生成内容，极大提升体验。前端处理流式数据（Server-Sent Events或WebSocket）的代码稍复杂，但绝对值得。

4. 分离配置与代码：不要将模型名称、API地址、超时时间等硬编码在代码里。使用环境变量或配置文件来管理它们。这样在不同环境（开发、测试、生产）部署时会非常方便。

5. 监控与日志：在生产环境中，记录下每次API调用的模型、输入token数、输出token数、耗时和可能发生的错误。这能帮你分析使用情况、定位性能瓶颈和计算成本（如果未来使用付费API的话）。

6. 理解模型特性：不同的模型有各自的强项和弱点。CodeLlama擅长编程，Llama 3通用能力强，Mistral在某些推理任务上表现突出。根据你的应用场景选择合适的模型，或者让用户自己选择。

最后，Ollama的生态在快速发展，新的模型和功能不断加入。保持关注其官方GitHub仓库和文档，是跟上最新进展的最好方式。我自己的习惯是，每过一两个月就去看看有没有新出的、更小更强的模型，或者API有没有增加什么好用的新参数。技术的乐趣就在于不断探索和优化，希望这份实战指南能成为你探索本地AI世界的一块坚实跳板。如果在实践中遇到具体问题，多看看日志，多尝试调整参数，大多数问题都能找到解决路径。