企业官网建设流程全解析

UFO 接入 Ollama 本地大模型：从安装配置到源码级原理详解

【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO

UFO（UI-Focused Agent for Windows OS Interaction）默认依赖云端 LLM，而 Ollama 为核心骨架，结合 ufo/llm/ollama.py 等源码实现，完整讲解 Ollama 的安装、模型拉取、UFO 配置、上下文窗口扩容与底层调用原理，帮助你在一台无外网依赖或对数据隐私敏感的环境中，跑通一套端到端的本地桌面智能体。

Ollama 在 UFO 中的定位

在 Model Configuration Overview 中，UFO 将 Ollama 归类为"本地模型"提供方：它不需要 API Key，请求发往本机服务，因此天然适合隐私敏感场景与开发期快速迭代。与 OpenAI、Azure OpenAI 等云端服务相比，Ollama 的视觉能力受限（仅llava等视觉模型支持截图理解），JSON Schema 支持也有限——这意味着使用纯文本模型时，UFO 会将输出切换为文本解析模式，而非严格的结构化输出。

从源码结构看，Ollama 是 UFO 众多 LLM 后端中的一员：ufo/llm/base.py 中的service_map将字符串"ollama"映射到OllamaService，UFO 根据你在配置里填写的API_TYPE动态加载对应服务类，接口统一收敛到chat_completion方法。

Step 1：安装并启动 Ollama

Ollama 官方提供了多平台安装方式，Linux 与 WSL2 环境使用一键安装脚本：

# 安装 Ollama curl https://ollama.ai/install.sh | sh # 启动 Ollama 服务端 ollama serve

Windows 与 macOS 用户则直接前往 Ollama 官网 下载对应安装包即可。安装完成后，Ollama 默认在http://localhost:11434启动一个 HTTP 服务端，这个地址稍后就是 UFO 配置中的API_BASE。

Step 2：拉取并测试模型

另开一个终端，拉取一个模型（文档以llama2为例）并验证可用性：

# 拉取模型（示例：llama2） ollama pull llama2 # 进入交互式对话验证模型可用 ollama run llama2

Ollama 支持从官方模型库拉取任意已发布的模型，例如llama3、qwen2、llava等。需要特别留意：UFO 的 HOST_AGENT 需要通过截图理解桌面状态（VISUAL_MODE: True），因此如果你打算让智能体具备视觉理解能力，应选择llava这类多模态模型；纯文本模型（如llama2）只能以文本模式工作，这在 overview.md 中被标注为"视觉支持有限"。

Step 3：配置 UFO 使用 Ollama

3.1 准备配置文件

UFO 使用 config/ufo/agents.yaml 存放所有 Agent 的 LLM 配置。该文件包含 API Key 等敏感信息，默认不随仓库提交，首次使用需从模板复制：

Copy-Item config\ufo\agents.yaml.template config\ufo\agents.yaml

3.2 填写 Ollama 配置

编辑config/ufo/agents.yaml，将HOST_AGENT与APP_AGENT的 API 配置替换为：

HOST_AGENT: VISUAL_MODE: True # 模型支持视觉时设为 True（如 llava） API_TYPE: "ollama" # 使用 Ollama API API_BASE: "http://localhost:11434" # Ollama 服务端地址 API_KEY: "ollama" # 占位值（实际不使用，但配置项必填） API_MODEL: "llama2" # 模型名，必须与已拉取的模型一致 APP_AGENT: VISUAL_MODE: True API_TYPE: "ollama" API_BASE: "http://localhost:11434" API_KEY: "ollama" API_MODEL: "llama2"

3.3 配置字段说明

3.4 为什么API_KEY是必填的

从 ufo/llm/ollama.py 可以看到，OllamaService在初始化时强制将API_KEY覆盖为"ollama"，然后以openai兼容协议把API_BASE + "/v1"作为请求地址，复用BaseOpenAIService的客户端实现。因此API_KEY在配置文件中只是占位符，真正生效的是API_BASE与API_MODEL。

关键前提：扩大模型上下文长度

UFO 正常运行至少需要 20,000 token 的上下文窗口，而 Ollama 默认上下文长度为 2048 token，远远不够。若不处理，UFO 会因上下文不足而无法输出完整的动作规划。解决方法是通过Modelfile创建自定义模型：

1. 创建Modelfile文件：

FROM llama2 PARAMETER num_ctx 32768

2. 构建自定义模型：

ollama create llama2-max-ctx -f Modelfile

3. 在配置中使用该自定义模型：

API_MODEL: "llama2-max-ctx"

num_ctx表示上下文窗口的 token 数，32768是文档给出的推荐值；上下文越大，对本地显存/内存的占用也越高，你可根据机器配置调整。详细的 Modelfile 参数说明可查阅 Ollama 官方 Modelfile 文档。

源码级原理：UFO 如何调用 Ollama

服务注册与动态加载

当API_TYPE为ollama时，ufo/llm/base.py 的service_map命中"ollama": "OllamaService"，随后通过import_module("." + name.lower(), package="ufo.llm")动态导入 ufo/llm/ollama.py 并实例化服务。get_service使用functools.cache缓存服务实例，避免重复创建客户端。

与 OpenAI 协议对齐

OllamaService继承自BaseOpenAIService（见 ufo/llm/openai.py），构造时将API_BASE拼接为http://localhost:11434/v1作为 OpenAI 客户端的base_url，这意味着Ollama 的/v1/chat/completions兼容端点直接复用了 OpenAI SDK 的请求管线，包括重试（MAX_RETRY）、超时（TIMEOUT）、温度（TEMPERATURE）等全局参数。

JSON 结构化输出与文本模式回退

chat_completion在调用底层_chat_completion时传入response_format={"type": "json_object"}，要求模型以 JSON 返回，便于 UFO 解析动作序列。但如 overview 所述，Ollama 的 JSON Schema 支持有限：当模型不支持结构化输出时，ufo/llm/openai.py 中的启动探针会自动将JSON_SCHEMA降级为False，切换到文本解析模式，保证流程不被阻塞。

全局参数来自哪里

MAX_RETRY、TIMEOUT、TEMPERATURE、TOP_P、MAX_TOKENS等参数由 ufo/llm/base.py 从全局配置聚合后注入服务；对 UFO 而言，这些值的默认来源是 config/ufo/system.yaml，例如MAX_TOKENS: 2000、MAX_RETRY: 20、TIMEOUT: 60。你可以按需调整这些全局参数，控制 Ollama 本地推理的稳定性与输出长度。

备用引擎机制

如果 Ollama 请求失败（如模型未拉取、服务未启动、上下文超限），ufo/llm/llm_call.py 会捕获异常并自动切换到BACKUP_AGENT作为备用引擎。因此你也可以为BACKUP_AGENT配置一个云端模型作为兜底，实现"本地优先、云端保底"的混合架构。

Step 4：启动 UFO 并验证

配置完成后，参照 Quick Start Guide 启动 UFO：

# 交互式模式 python -m ufo --task <your_task_name> # 直接指定任务请求 python -m ufo --task email_demo -r "Send an email to john@example.com with subject 'Meeting Reminder'"

验证要点：

• 启动前确认 Ollama 服务正在运行（ollama serve），且API_MODEL对应的模型已通过ollama pull/ollama create就绪；
• 观察./logs/<your_task_name>/request_response.log，确认请求确实发往http://localhost:11434；
• 若模型不支持视觉，将VISUAL_MODE设为False，避免向纯文本模型发送截图。

常见问题排查

延伸阅读

• Agent Configuration Guide —— 完整的 Agent 配置参考（含其他提供方示例）
• Model Configuration Overview —— 各 LLM 提供方能力对比与选型指南
• Quick Start Guide —— UFO 安装与首次运行完整流程
• ufo/llm/ollama.py —— Ollama 服务实现源码
• ufo/llm/base.py —— 服务注册与全局参数注入逻辑

【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO