企业官网建设流程全解析

ai-agent-book 如何用 Ollama 或 vLLM 部署本地 LLM 服务并完成工具调用

【免费下载链接】ai-agent-book《深入理解 AI Agent：设计原理与工程实践》（李博杰 著）开源主仓库：全书正文、编译版 PDF 与按章配套代码项目地址: https://gitcode.com/GitHub_Trending/ai/ai-agent-book

在 ai-agent-book 仓库的第 2 章配套项目chapter2/local_llm_serving中，目标是把一个小模型跑在本地，并通过 OpenAI 兼容的工具调用格式让它调用天气、时间、汇率、PDF 解析、代码解释器等内置工具。两条部署路径：Linux/WSL2 + NVIDIA GPU 走 vLLM，macOS、原生 Windows 和无 GPU 的 Linux 走 Ollama。无论哪条路径，统一入口都是main.py，需要显式传入--backend参数，避免程序仅因检测到 CUDA 就选择你没有安装的后端。

选择后端：先看你的平台

两条路径的适用条件在 README 中是明确的：

vLLM 官方 GPU 执行环境要求 Linux。想在 Windows 机器上使用 vLLM，需要在支持 CUDA 的 WSL2 或 Linux 容器中运行本项目；社区维护的原生 Windows 移植版不在项目支持的配置之内。

准备 Python 环境

全平台统一要求 Python 3.12，并在仓库根目录安装第 2 章环境ch2extra：

# 仓库根目录，安装共享的第 2 章环境 uv sync --locked --python 3.12 --extra ch2 # 仅 Linux/WSL 走 vLLM 路径时才加 --extra vllm（会拉取 Linux/GPU vLLM 栈） # uv sync --locked --python 3.12 --extra ch2 --extra vllm # 未安装 uv 时的 pip 兜底： # python -m pip install -e ".[ch2]" # vLLM 路径的 pip 兜底：python -m pip install -e ".[ch2,vllm]"

默认ch2安装不含 vLLM 依赖，保留 Ollama 路径可用。切换目录前先激活环境：

# macOS/Linux： source .venv/bin/activate # Windows PowerShell：.venv\Scripts\Activate.ps1 # Windows cmd：.venv\Scripts\activate.bat # 进入项目目录 cd chapter2/local_llm_serving

迁移期间仍支持单项目兼容路径python -m pip install -r requirements.txt。

Ollama 路径：安装、拉取模型并启动

按平台安装 Ollama 服务并拉取默认模型：

# macOS brew install ollama ollama serve # 在另一个终端运行 ollama pull qwen3:0.6b

# 无 GPU 的 Linux（安装脚本会写入系统，需要 sh 执行权限） curl -fsSL https://ollama.com/install.sh | sh systemctl start ollama ollama pull qwen3:0.6b

原生 Windows 从 Ollama 官网下载安装包，安装后同样执行ollama pull qwen3:0.6b。

vLLM 路径：兼容性检查与服务启动

先安装带vllmextra 的环境（上一步已给出命令），然后运行兼容性检查，它会报告 OS、架构、nvidia-smi查询到的 GPU、PyTorch CUDA 可用性，并根据结果给出该走 vLLM 还是 Ollama 的建议：

python check_compatibility.py

注意check_compatibility.py仅用于 Linux/WSL2 vLLM 路径；原生 Windows 应直接使用 Ollama 后端。

vLLM 服务的启动有两种方式：

• 由main.py自动拉起：运行时先探测http://localhost:8000/health，不可达则自动启动 server.py 中的VLLMServer，轮询/health直到返回 200，再请求/v1/models确认模型可用，超时上限 120 秒，日志写入logs/vllm_server.log。
• 手动启动：python server.py直接启动 vLLM 服务进程，可选参数--download（先从 ModelScope 下载模型）、--model、--port、--host覆盖 config.py 中的配置。

实际拼出的 vLLM 启动命令形如：

python -m vllm.entrypoints.openai.api_server \ --model Qwen/Qwen3-0.6B --port 8000 --host localhost \ --enable-auto-tool-choice --tool-call-parser hermes \ --max-model-len 8192 --gpu-memory-utilization 0.9 --dtype auto

如需自定义连接参数，把env.example复制为.env：

MODEL_NAME=Qwen/Qwen3-0.6B VLLM_HOST=localhost VLLM_PORT=8000 LOG_LEVEL=INFO

运行工具调用任务并验证结果

在chapter2/local_llm_serving目录下执行。单任务模式是最短验证路径——以--backend ollama为例，vLLM 路径只需把参数换成--backend vllm：

# 单任务模式：验证模型是否真的调用了工具 python main.py --backend ollama --mode single --task "What's the weather in Tokyo?" # 交互模式 python main.py --backend ollama --mode interactive # 查看系统信息（平台、Python、CUDA、ollama 包是否安装） python main.py --backend ollama --info

判断部署成功的依据来自输出本身：

1. 启动日志先出现✅ Agent ready! Using ollama backend（或vllm）。Ollama 路径会检查已安装模型列表；如果qwen3:0.6b不在其中，程序会提示ollama pull qwen3:0.6b，并回退到第一个可用模型。
2. 单任务模式默认流式输出，依次出现思考内容（thinking）、工具调用（tool_call，含工具名与参数）、工具结果（tool_result）、最终回复（content）。看到工具名与参数被实际执行，再得到整合了工具结果的最终答案，即说明工具调用链路打通。
3. 交互模式启动时会列出可用工具清单，支持/tools查看工具、/sample <n>运行内置示例任务（如多城市天气对比、复利计算）、/reset重置会话、/stream切换流式。

内置工具及其数据源：get_current_temperature（Open-Meteo，无需 API Key）、get_current_time（多时区）、convert_currency（模拟汇率）、parse_pdf（URL 或本地文件）、code_interpreter（执行 Python）。模型输出的工具调用为标准 OpenAI 兼容格式，工具结果回灌给模型后生成最终回复；同一轮多个工具调用会并行执行。

vLLM 侧的连通性也可独立核对：服务就绪后/health返回 200，/v1/models列出Qwen/Qwen3-0.6B。服务默认地址与模型名对应关系为：vLLMQwen3-0.6B@:8000/v1，Ollamaqwen3:0.6b@:11434/v1。

模型选择与常见问题

默认模型为 Qwen3 0.6B（小、工具调用表现尚可）。文档中列出工具调用表现较好的还有 Qwen3 8B+、Llama 3.1/3.2 8B+、Mistral Nemo；vLLM 默认Qwen/Qwen3-0.6B，可配置任意 vLLM 支持的模型。

故障排除按 README 的条目处理：

• 找不到 Ollama：按上文平台对应的安装方式装好并启动服务（macOS 可brew services start ollama或ollama serve，Linux 用systemctl start ollama，Windows 从系统托盘启动）。
• 没有模型：ollama pull qwen3:0.6b。
• CUDA 不可用：走 vLLM 路径需为 vLLM 安装驱动/CUDA；不想处理就改用python main.py --backend ollama。
• 原生 Windows 检测到 CUDA：原生 Windows 固定使用 Ollama；vLLM 请用 WSL2 或 Linux 容器。

流式输出可通过--no-stream关闭，交互会话中用/stream切换。项目结构见 README 项目结构一节，核心文件为 main.py（统一入口）、agent.py（vLLM 端 ReAct 循环）、ollama_native.py（Ollama 原生工具调用）、tools.py（工具实现）。

【免费下载链接】ai-agent-book《深入理解 AI Agent：设计原理与工程实践》（李博杰 著）开源主仓库：全书正文、编译版 PDF 与按章配套代码项目地址: https://gitcode.com/GitHub_Trending/ai/ai-agent-book