1. from ollama import chat：导入 Ollama Python SDK 中的核心对话函数 chat，该函数是发起所有对话请求的入口。
2. chat() 函数的核心参数：

• model：指定要使用的模型名称，需确保模型已本地下载（可通过 ollama list 查看已下载模型）。
• messages：对话历史列表，每个元素是包含 role（角色）和 content（内容）的字典，role 支持 user（用户）、assistant（助手）、tool（工具）三种类型。
• stream=True：开启流式模式，此时函数返回的不再是完整响应对象，而是一个可迭代的 stream 对象，每次迭代获取一个内容块。

# 初始化状态变量和累积变量
in_thinking = False  # 标记是否正处于模型“思考”阶段（用于区分思考和正式回答）
content = ""  # 累积模型的正式回答内容
thinking = ""  # 累积模型的推理过程内容

# 迭代 stream 对象，逐块处理响应
for chunk in stream:
    # 场景1：当前 chunk 包含模型的思考过程（仅支持 Thinking 模式的模型会返回该字段）
    if chunk.message.thinking:
        # 如果是第一次收到思考内容，打印“Thinking:”标题
        if not in_thinking:
            in_thinking = True
            print('Thinking:\n', end='', flush=True)  # end='' 不自动换行，flush=True 强制立即输出
        # 实时打印当前 chunk 的思考内容，并累加到 thinking 变量中
        print(chunk.message.thinking, end='', flush=True)
        thinking += chunk.message.thinking

    # 场景2：当前 chunk 包含模型的正式回答内容
    elif chunk.message.content:
        # 如果之前处于思考阶段，先换行切换到“Answer:”标题
        if in_thinking:
            in_thinking = False
            print('\n\nAnswer:\n', end='', flush=True)
        # 实时打印当前 chunk 的正式回答，并累加到 content 变量中
        print(chunk.message.content, end='', flush=True)
        content += chunk.message.content

1.4 下一步：将累积内容加入对话历史

# 构造完整的助手响应消息，包含累积的思考过程和正式回答
new_message = {
    'role': 'assistant',  # 角色为助手
    'thinking': thinking,  # 完整的推理过程
    'content': content     # 完整的正式回答
}

# 将新消息添加到原对话历史中（假设原对话历史存储在 messages 列表中）
messages.append(new_message)

• 直接机器可读：返回的 JSON 数据可直接用于程序逻辑、数据库导入、API 调用等场景。
• 数据一致性：避免模型输出格式混乱，即使多次调用，返回结构也保持统一。
• 减少解析成本：无需手动处理自由文本，直接通过键名提取所需信息。

• 实体信息提取（人名、地点、价格、日期等）。
• 图像描述标准化（固定字段描述图像中的物体、场景、颜色等）。
• 数据库批量导入（按表结构生成 JSON 数据）。
• 确定性响应需求（配合 temperature=0，确保输出格式 100% 符合预期）。

# cURL 命令示例：返回关于加拿大的标准 JSON 数据
curl -X POST http://localhost:11434/api/chat \
-H "Content-Type: application/json" \
-d '{
    "model": "gpt-oss",  # 推荐使用支持结构化输出的模型
    "messages": [{"role": "user", "content": "Tell me about Canada in one paragraph."}],
    "stream": false,  # 结构化输出不支持流式，需关闭
    "format": "json"  # 指定输出格式为 JSON
}'

响应示例：

{
  "message": {
    "role": "assistant",
    "content": "{\"name\":\"Canada\",\"capital\":\"Ottawa\",\"languages\":[\"English\",\"French\"],\"continent\":\"North America\",\"population\":\"approximately 39 million\"}"
  },
  "done": true
}

注意：仅指定 format: "json" 时，模型可能不完全遵守预期结构（例如缺少字段、字段类型错误）。对于关键场景，推荐使用自定义 JSON Schema。

3.3 高级用法：自定义 JSON Schema

通过定义 JSON Schema，明确指定返回数据的字段名、类型、必填项等，确保模型输出完全符合需求。以下是完整示例：

步骤 1：定义 JSON Schema

需求：获取加拿大的名称、首都、官方语言，Schema 定义如下：

{
  "type": "object",  # 根节点为对象类型
  "properties": {
    "name": {"type": "string"},  # 国家名称（字符串类型）
    "capital": {"type": "string"},  # 首都（字符串类型）
    "languages": {  # 官方语言（数组类型，元素为字符串）
      "type": "array",
      "items": {"type": "string"}
    }
  },
  "required": ["name", "capital", "languages"]  # 必填字段，缺一不可
}

步骤 2：发起 cURL 请求

将自定义 Schema 传入 format 参数：

curl -X POST http://localhost:11434/api/chat \
-H "Content-Type: application/json" \
-d '{
    "model": "gpt-oss",
    "messages": [{"role": "user", "content": "Tell me about Canada."}],
    "stream": false,
    "format": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "capital": {"type": "string"},
        "languages": {"type": "array", "items": {"type": "string"}}
      },
      "required": ["name", "capital", "languages"]
    }
}'

响应示例（严格符合 Schema）：

{
  "message": {
    "role": "assistant",
    "content": "{\"name\":\"Canada\",\"capital\":\"Ottawa\",\"languages\":[\"English\",\"French\"]}"
  },
  "done": true
}

3.4 Python 示例：使用 Pydantic 定义结构（推荐）

Pydantic 是 Python 中常用的数据验证库，可通过类定义自动生成 JSON Schema，同时支持类型验证和 IDE 自动补全，比手动编写 Schema 更高效。

示例：提取宠物信息

需求：根据用户输入的宠物描述，提取宠物名称、种类、年龄、颜色、喜欢的玩具等信息。

# 1. 导入必要的库
from ollama import chat
from pydantic import BaseModel  # Pydantic 核心类，用于定义数据结构

# 2. 定义 Pydantic 模型（自动生成 JSON Schema）
class Pet(BaseModel):
    name: str  # 宠物名称（必填，字符串）
    animal: str  # 宠物种类（必填，字符串，如 cat、dog）
    age: int  # 年龄（必填，整数）
    color: str | None = None  # 颜色（可选，字符串，默认 None）
    favorite_toy: str | None = None  # 喜欢的玩具（可选，字符串，默认 None）

# 定义包含多个宠物的列表模型
class PetList(BaseModel):
    pets: list[Pet]  # 宠物列表（必填，元素为 Pet 类型）

# 3. 发起 Ollama 请求
response = chat(
    model='gpt-oss',  # 支持结构化输出的模型
    messages=[
        {
            'role': 'user',
            'content': 'I have two cats named Luna and Loki. Luna is 3 years old, black, loves yarn. Loki is 5, orange, likes boxes.'
        }
    ],
    format=PetList.model_json_schema(),  # 自动将 Pydantic 模型转换为 JSON Schema
    options={'temperature': 0}  # 温度设为 0，确保输出完全符合结构，无随机性
)

# 4. 解析并验证返回结果
# model_validate_json 会自动验证 JSON 结构是否符合 PetList 模型，不符合则报错
pets = PetList.model_validate_json(response.message.content)

# 5. 打印结果（支持属性访问，如 pets.pets[0].name）
print(pets)

输出示例：

PetList(pets=[
    Pet(name='Luna', animal='cat', age=3, color='black', favorite_toy='yarn'),
    Pet(name='Loki', animal='cat', age=5, color='orange', favorite_toy='boxes')
])

3.5 视觉模型 + 结构化输出：精准图像识别

# 1. 导入必要的库和类型
from typing import Literal, Optional
from pydantic import BaseModel
from ollama import chat

# 2. 定义图像描述的结构化模型
class Object(BaseModel):
    name: str  # 物体名称（如 cat、window）
    confidence: float  # 识别置信度（0-1 之间）
    attributes: str  # 物体属性（如 black fur、wooden frame）

class ImageDescription(BaseModel):
    summary: str  # 图像概要描述
    objects: list[Object]  # 识别到的物体列表
    scene: str  # 场景描述（如 indoor living room）
    colors: list[str]  # 主要颜色列表
    time_of_day: Literal['Morning', 'Afternoon', 'Evening', 'Night']  # 时间段（仅允许指定选项）
    setting: Literal['Indoor', 'Outdoor', 'Unknown']  # 场景类型（仅允许指定选项）
    text_content: Optional[str] = None  # 图像中的文字内容（可选）

# 3. 发起带图像的结构化请求
response = chat(
    model='gemma3',  # 支持视觉功能的模型
    messages=[
        {
            'role': 'user',
            'content': 'Describe this photo and list the objects you detect.',  # 指令：描述照片并列出检测到的物体
            'images': ['path/to/cat_image.jpg']  # 本地图像路径，SDK 会自动处理
        }
    ],
    format=ImageDescription.model_json_schema(),  # 结构化输出格式
    options={'temperature': 0}  # 关闭随机性，确保格式一致
)

# 4. 解析结果
image_desc = ImageDescription.model_validate_json(response.message.content)
print(image_desc)

ImageDescription(
    summary='A black cat sleeping on a windowsill during evening.',
    objects=[
        Object(name='cat', confidence=0.98, attributes='black fur, closed eyes'),
        Object(name='window', confidence=0.92, attributes='wooden frame')
    ],
    scene='indoor living room',
    colors=['black', 'brown', 'white'],
    time_of_day='Evening',
    setting='Indoor',
    text_content=None
)

• 图像内容描述：用自然语言详细描述图像中的场景、物体、人物动作等。
• OCR 文字识别：提取图像中的文字内容（如海报上的文字、文档扫描件中的文字）。
• 物体检测与分类：识别图像中的物体类别、位置及属性（如 “黑色的猫”“木质窗户”）。
• 场景问答（VQA）：根据文本指令回答与图像相关的问题（如 “这张图中有几只狗？”“图中的文字是什么意思？”）。

• 模型会自动读取本地图像文件并编码，无需手动处理。
• 文本指令需明确，例如 “描述图像中的物体”“提取图像中的文字”“判断图像是室内还是室外”。
• 输出为自然语言文本，若需结构化输出，需结合上一章节的 Structured Outputs 功能。

# 1. 下载测试图像（以维基百科的猫图片为例）
curl -L -o test.jpg "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"

# 2. 将图像转换为 Base64 字符串（去除换行符，避免 JSON 解析错误）
IMG=$(base64 < test.jpg | tr -d '\n')

# 3. 向 Ollama API 发送请求
curl -X POST http://localhost:11434/api/chat \
-H "Content-Type: application/json" \
-d '{
    "model": "gemma3",  # 支持 Vision 的模型
    "messages": [
        {
            "role": "user",
            "content": "What is in this image? Describe the animal's appearance.",  # 指令：描述图像中的动物外观
            "images": ["'"$IMG"'"]  # 传入 Base64 编码的图像字符串
        }
    ],
    "stream": false  # 视觉模型暂不支持流式输出
}'

响应示例：

{
  "message": {
    "role": "assistant",
    "content": "The image shows a cat with light-colored fur, possibly white or cream. The cat appears to be lying down, with its eyes open and looking towards the camera. Its ears are pointed, and it has a calm expression. The background is blurred, focusing attention on the cat."
  },
  "done": true
}

4.4 Python SDK 使用本地路径（更简单）

Ollama Python SDK 简化了图像处理流程，支持直接传入本地文件路径，SDK 会自动将图像转换为 Base64 编码，无需手动处理：

# 1. 导入 chat 函数
from ollama import chat

# 2. 发起带图像的请求
response = chat(
    model='gemma3',  # 支持 Vision 的模型
    messages=[
        {
            'role': 'user',
            'content': 'Describe the animal in this picture. Is it a cat or a dog?',  # 指令：描述动物并判断种类
            'images': ['test.jpg']  # 直接传入本地图像路径（相对路径或绝对路径均可）
        }
    ]
)

# 3. 打印结果
print(response.message.content)

输出示例：

The animal in the picture is a cat. It has light-colored fur, pointed ears, and a slender face. The cat is in a relaxed posture, likely resting on a soft surface. The fur appears smooth and well-groomed.

4.5 支持的数据类型

• “猫” 的向量与 “狗” 的向量距离较近（均为宠物）。
• “猫” 的向量与 “汽车” 的向量距离较远（语义无关）。

• 语义相似度匹配：计算两个文本的余弦相似度（cosine similarity），判断其语义是否相近。
• 向量数据库检索：将文本嵌入后存入向量数据库（如 Pinecone、Weaviate、Chroma），快速检索语义相关的文本。
• RAG（Retrieval-Augmented Generation）：检索与用户问题相关的知识库文本，作为上下文传入模型，提升回答的准确性和时效性。

• 用户问 “纽约现在的气温是多少？”，模型会调用天气 API 获取实时数据，再返回 “纽约当前气温为 22°C”。
• 用户问 “(11434+12341)×412 等于多少？”，模型会调用计算器工具分步计算，再返回最终结果。

{
  "type": "function",
  "function": {
    "name": "get_temperature",  # 工具名称（需与实际函数名一致）
    "description": "Get current temperature for a city",  # 工具功能描述
    "parameters": {
      "type": "object",
      "required": ["city"],  # 必填参数
      "properties": {
        "city": {"type": "string", "description": "City name"}  # 参数说明：城市名称（字符串）
      }
    }
  }
}

步骤 2：发起 API 请求

通过 cURL 发起工具调用请求，模型会返回工具调用指令：

curl -s http://localhost:11434/api/chat \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen3",  # 支持工具调用的模型
    "messages": [{"role": "user", "content": "What is the temperature in New York?"}],  # 用户问题
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_temperature",
                "description": "Get current temperature for a city",
                "parameters": {
                    "type": "object",
                    "required": ["city"],
                    "properties": {
                        "city": {"type": "string", "description": "City name"}
                    }
                }
            }
        }
    ],
    "stream": false
}'

步骤 3：模型返回工具调用指令

模型会判断需要调用 get_temperature 工具，并传入参数 city: "New York"：

{
  "message": {
    "role": "assistant",
    "tool_calls": [
      {
        "type": "function",
        "function": {
          "name": "get_temperature",
          "arguments": {"city": "New York"}
        }
      }
    ]
  },
  "done": false  # done 为 false，表示需要继续工具调用
}

6.3 执行工具并返回结果

拿到模型的工具调用指令后，需执行对应的外部工具（如调用天气 API），再将工具返回的结果传入模型，让模型生成最终回答。

# 执行工具后，将结果加入对话历史，发起第二次请求
curl -s http://localhost:11434/api/chat \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen3",
    "messages": [
        {"role": "user", "content": "What is the temperature in New York?"},  # 原用户问题
        {"role": "assistant", "tool_calls": [{"type": "function", "function": {"name": "get_temperature", "arguments": {"city": "New York"}}}]},  # 模型的工具调用指令
        {"role": "tool", "tool_name": "get_temperature", "content": "22°C"}  # 工具返回的结果
    ],
    "stream": false
}'

模型返回最终回答：

{
  "message": {
    "role": "assistant",
    "content": "The temperature in New York is 22°C."
  },
  "done": true
}

6.4 并行工具调用

模型支持同时调用多个工具，一次性获取多个结果后综合回答，适用于需要多源数据的场景（如查询 “纽约的气温和天气状况”）。

curl -s http://localhost:11434/api/chat \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen3",
    "messages": [{"role": "user", "content": "What is the temperature and weather condition in New York?"}],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_temperature",
                "description": "Get current temperature for a city",
                "parameters": {"type": "object", "required": ["city"], "properties": {"city": {"type": "string"}}}
            }
        },
        {
            "type": "function",
            "function": {
                "name": "get_weather_condition",
                "description": "Get current weather condition (sunny/rainy/cloudy) for a city",
                "parameters": {"type": "object", "required": ["city"], "properties": {"city": {"type": "string"}}}
            }
        }
    ],
    "stream": false
}'

模型返回并行工具调用指令：

{
  "message": {
    "role": "assistant",
    "tool_calls": [
      {"type": "function", "function": {"name": "get_temperature", "arguments": {"city": "New York"}}},
      {"type": "function", "function": {"name": "get_weather_condition", "arguments": {"city": "New York"}}}
    ]
  },
  "done": false
}

执行工具后返回结果：

{
  "message": {
    "role": "assistant",
    "content": "The temperature in New York is 22°C and the weather condition is sunny."
  },
  "done": true
}

6.5 多轮 Agent 循环（Multi-turn Tool Calling）

多轮工具调用是指模型需要多次调用工具（可能是同一个或不同工具），逐步推进问题解决，适用于复杂任务（如多步计算、多条件查询）。

以下是 Python 实现的多轮工具调用示例，解决 “(11434+12341)×412 等于多少？” 的问题：

# 1. 导入必要的库
from ollama import chat

# 2. 定义可用的工具函数
def add(a: int, b: int) -> int:
    """Add two numbers（加法函数）"""
    return a + b

def multiply(a: int, b: int) -> int:
    """Multiply two numbers（乘法函数）"""
    return a * b

# 3. 存储可用工具（键为工具名称，值为工具函数）
available_functions = {
    'add': add,
    'multiply': multiply
}

# 4. 初始化对话历史
messages = [{'role': 'user', 'content': 'What is (11434+12341)*412?'}]

# 5. 多轮工具调用循环
while True:
    # 发起对话请求，传入可用工具和思考模式
    response = chat(
        model='qwen3',
        messages=messages,
        tools=[add, multiply],  # 传入工具函数，模型会自动解析名称、参数
        think=True,  # 开启思考模式，查看模型的推理过程
    )

    # 将模型响应加入对话历史
    messages.append(response.message)

    # 检查是否需要调用工具
    if response.message.tool_calls:
        # 遍历每个工具调用指令
        for tc in response.message.tool_calls:
            # 获取对应的工具函数
            func = available_functions.get(tc.function.name)
            if func:
                # 执行工具函数（传入参数）
                result = func(**tc.function.arguments)
                # 将工具执行结果加入对话历史
                messages.append({
                    'role': 'tool',
                    'tool_name': tc.function.name,
                    'content': str(result)  # 工具结果需转为字符串
                })
    else:
        # 没有更多工具调用，退出循环
        break

# 6. 打印最终结果
print("Final Answer:", response.message.content)

输出示例：

Final Answer: (11434 + 12341) = 23775, then 23775 × 412 = 9795300. So the result is 9795300.

6.6 流式 + 工具调用：完整 Accumulation 示例

# 1. 导入库
from ollama import chat

# 2. 定义工具函数
def add(a: int, b: int) -> int:
    return a + b

available_functions = {'add': add}

# 3. 初始化对话历史和累积变量
messages = [{'role': 'user', 'content': 'What is 123 + 456?'}]
thinking = ""  # 累积思考过程
content = ""   # 累积正式回答
tool_calls = []  # 累积工具调用指令

# 4. 发起流式请求
stream = chat(
    model='qwen3',
    messages=messages,
    tools=[add],
    think=True,
    stream=True
)

# 5. 处理流式 chunk
for chunk in stream:
    # 累积思考过程
    if chunk.message.thinking:
        thinking += chunk.message.thinking
    # 累积正式回答
    if chunk.message.content:
        content += chunk.message.content
    # 累积工具调用指令
    if chunk.message.tool_calls:
        tool_calls.extend(chunk.message.tool_calls)

# 6. 将完整响应加入对话历史
messages.append({
    'role': 'assistant',
    'thinking': thinking,
    'content': content,
    'tool_calls': tool_calls
})

# 7. 执行工具并获取结果
if tool_calls:
    tc = tool_calls[0]
    func = available_functions.get(tc.function.name)
    result = func(**tc.function.arguments)
    messages.append({
        'role': 'tool',
        'tool_name': tc.function.name,
        'content': str(result)
    })

# 8. 生成最终回答
final_response = chat(model='qwen3', messages=messages)
print("Final Answer:", final_response.message.content)

Final Answer: 123 + 456 = 579.

• Vision + Structured Outputs：精准提取图像中的结构化信息。
• Embeddings + RAG + Tool Calling：构建具备知识库检索和工具使用能力的智能客服。
• Web Search + Tool Calling + Thinking：打造能实时搜索、自主推理、解决复杂问题的 AI Agent。