UFO 接入 Ollama 本地大模型从安装配置到源码级原理详解【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFOUFOUI-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映射到OllamaServiceUFO 根据你在配置里填写的API_TYPE动态加载对应服务类接口统一收敛到chat_completion方法。Step 1安装并启动 OllamaOllama 官方提供了多平台安装方式Linux 与 WSL2 环境使用一键安装脚本# 安装 Ollama curl https://ollama.ai/install.sh | sh # 启动 Ollama 服务端 ollama serveWindows 与 macOS 用户则直接前往 Ollama 官网 下载对应安装包即可。安装完成后Ollama 默认在http://localhost:11434启动一个 HTTP 服务端这个地址稍后就是 UFO 配置中的API_BASE。Step 2拉取并测试模型另开一个终端拉取一个模型文档以llama2为例并验证可用性# 拉取模型示例llama2 ollama pull llama2 # 进入交互式对话验证模型可用 ollama run llama2Ollama 支持从官方模型库拉取任意已发布的模型例如llama3、qwen2、llava等。需要特别留意UFO 的 HOST_AGENT 需要通过截图理解桌面状态VISUAL_MODE: True因此如果你打算让智能体具备视觉理解能力应选择llava这类多模态模型纯文本模型如llama2只能以文本模式工作这在 overview.md 中被标注为视觉支持有限。Step 3配置 UFO 使用 Ollama3.1 准备配置文件UFO 使用 config/ufo/agents.yaml 存放所有 Agent 的 LLM 配置。该文件包含 API Key 等敏感信息默认不随仓库提交首次使用需从模板复制Copy-Item config\ufo\agents.yaml.template config\ufo\agents.yaml3.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: llama23.3 配置字段说明字段取值说明VISUAL_MODETrue/False仅当模型具备视觉能力如llava时设为TrueAPI_TYPEollama指定 Ollama 后端源码中按小写匹配服务名务必使用小写API_BASEhttp://localhost:11434Ollama 服务端地址即默认监听端口API_KEYollama占位值Ollama 不需要真实密钥但配置中不可缺失API_MODEL模型名必须与ollama pull拉取的模型名完全一致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创建自定义模型创建Modelfile文件FROM llama2 PARAMETER num_ctx 32768构建自定义模型ollama create llama2-max-ctx -f Modelfile在配置中使用该自定义模型API_MODEL: llama2-max-ctxnum_ctx表示上下文窗口的 token 数32768是文档给出的推荐值上下文越大对本地显存/内存的占用也越高你可根据机器配置调整。详细的 Modelfile 参数说明可查阅 Ollama 官方 Modelfile 文档。源码级原理UFO 如何调用 Ollama服务注册与动态加载当API_TYPE为ollama时ufo/llm/base.py 的service_map命中ollama: OllamaService随后通过import_module(. name.lower(), packageufo.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 johnexample.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避免向纯文本模型发送截图。常见问题排查现象可能原因处理方式请求失败并自动切换备用引擎Ollama 服务未启动或模型未拉取先执行ollama serve与ollama pull model模型输出被截断、任务规划不完整上下文窗口不足默认仅 2048 token按上文Modelfile方式创建num_ctx更大的自定义模型无法识别截图内容使用了纯文本模型改用llava等视觉模型或将VISUAL_MODE设为False配置报API_TYPE 不支持API_TYPE大小写不一致源码按小写匹配务必填写ollama延伸阅读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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考