企业官网建设流程全解析

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手

Ollama 是开源的本地大模型运行时，它把语言模型直接跑在你自己的设备上，通过本地 API 提供推理服务，默认不需要 API Key。本文以 AIRI 的「意识（Consciousness）聊天模块」为核心场景，完整讲解如何安装 Ollama、下载并运行模型、在 AIRI 设置中接入本地服务、用自动校验与 Ping API 确认连通，以及如何处理跨设备访问与 CORS 报错。读完本文，你将掌握一条完全不依赖云端 API 的 AIRI 聊天链路，并理解其背后从设置界面到 provider 校验的完整实现原理。

为什么选择 Ollama

对 AIRI 用户来说，Ollama 的价值集中在三点：

• 本机运行模型：模型权重、推理过程全部发生在本机，对话数据不需要上传到任何云端服务；
• 减少云端 API 依赖：无需申请、管理 API Key，也不用担心配额和计费；
• 重视本地数据处理：如果你的场景对对话隐私或本地化处理有明确要求，Ollama 是合适的聊天提供者。

从仓库实现看，Ollama 在 AIRI 中被定义为一个完整的聊天 provider（tasks: ['chat']），与 OpenRouter、DeepSeek、OpenAI Compatible 等并列出现在「设置 → 服务商 → 聊天」列表中，具体见 provider 注册实现 与 Ollama provider 定义。

第一步：安装 Ollama

1. 访问 Ollama 官方网站，下载并安装适合自己操作系统的版本（Windows、macOS、Linux 均有对应安装包）；
2. 在终端（Terminal）或 PowerShell 中执行以下命令确认安装成功：

ollama --version

看到版本号输出即说明运行环境就绪。若该命令无法识别，请检查安装路径是否已加入系统 PATH。

第二步：下载并运行模型

执行以下命令，Ollama 会自动下载并启动一个模型：

ollama run qwen2

• 如需使用其他模型，把qwen2替换为对应的模型 ID 即可；
• 首次下载时间取决于模型大小和网络环境，模型越大、网络越慢，等待越久；
• 下载完成后模型会常驻本地，后续启动无需重新下载。

下载成功后，Ollama 默认会在11434端口提供两种 API：原生 API（http://localhost:11434/）和 OpenAI 兼容 API（http://localhost:11434/v1/）。AIRI 使用的是后者。

第三步：在 AIRI 中配置 Ollama

1. 打开设置 → 服务商 → 聊天 → Ollama；
2. 保留默认 Base URL：http://localhost:11434/v1/。如果 Ollama 运行在其他设备上，请填写从 AIRI 所在设备可以访问到的地址（例如局域网 IP 形式http://192.168.x.x:11434/v1/）；
3. 在设置 → 模块 → 意识中选择 Ollama 与刚才下载的模型。

配置项详解（结合源码）

Ollama 在 AIRI 中实际可配置的字段由 provider 配置 schema 定义，共三项：

其中thinkingMode和headers属于高级设置。思考模式会被映射为 OpenAI 兼容协议下的reasoningEffort：disable映射为none、enable映射为medium、low/medium/high原样透传、auto则不附加该参数（见 resolveOllamaReasoningEffort 实现）。如果请求级别明确指定了 reasoning 开关，则enabled → medium、disabled → none（见 createProvider 实现）。

对应设置页面 ollama.vue 提供了 Base URL 输入框、思考模式下拉框和请求头键值对编辑器，所有字段一旦修改会立即持久化并自动触发一次重新校验（watch([baseUrl, thinkingMode, headers], refetch)），页面挂载时会用已保存的配置或默认值初始化表单。

第四步：验证配置

AIRI 会在编辑配置的过程中自动校验，无需手动保存后再检查：

• 字段级校验（validateConfig）：检查 Base URL 是否为空、是否为合法且带 host 的绝对 URL（见 ollama provider 校验器）；
• 连通性校验（Connectivity）：对{baseUrl}/models发起 GET 请求，10 秒超时；
• 模型列表校验（ModelList）：拉取 Ollama 返回的模型列表，确认服务可用；
• 聊天补全校验（ChatCompletions）：向模型发送一条ping探测消息（max_tokens: 16），验证真实推理链路。

以上校验通过 OpenAI 兼容校验器统一调度，默认每 15 秒按间隔模式复查一次（见 openai-compatible 校验器）。

• Ping API：如果校验页面出现Ping API按钮，说明该 provider 提供真实请求测试能力，点击即可发起一次实际推理请求来确认端到端连通；
• 选择模型 →：校验通过后，点击此按钮会直接跳转到设置 → 模块 → 意识（对应代码中的路由/settings/modules/consciousness），选择你已下载的模型并完成激活。

注意：保存 provider 凭据并不会自动激活该 provider，必须回到「意识」模块同时选定 provider 和模型，AIRI 才会真正使用它生成回复。这是聊天模型配置的通用规则，详见 聊天模型设置指南。

配置完成后，回到聊天界面发送一条类似 "Hello" 的短消息。如果收到回复，说明 Ollama 已作为 AIRI 的"大脑"正常工作。

问题排查

AIRI 无法连接本地 Ollama

按以下顺序检查：

1. Ollama 是否在运行：在终端执行ollama list，确认服务进程存在；
2. 端口是否匹配：确认 Base URL 使用了正确的端口（默认11434）且带/v1/路径，与 默认配置 保持一致；
3. 跨设备访问：如果 AIRI 与 Ollama 不在同一台设备，请使用从 AIRI 设备可访问的局域网地址，并只在可信网络中开放该服务；不要直接把服务暴露到公网。

遇到 CORS 报错

如果 Ollama 明明在运行，AIRI 却报告 CORS（跨域资源共享）错误，这是浏览器/桌面环境向本地服务发起跨域请求被拒绝的典型表现。AIRI 的 provider 实现会在连通性检查失败时给出明确提示：需要为 Ollama 设置OLLAMA_ORIGINS环境变量，把 AIRI 的精确 origin 加进去，然后重启 Ollama（见 ollama provider 的失败原因文案）。

推荐写法示例（按你的启动方式选择其一）：

# macOS / Linux OLLAMA_ORIGINS=http://localhost:5173 ollama serve # Windows PowerShell（按官方文档设置环境变量后重启 Ollama 服务） $env:OLLAMA_ORIGINS="http://localhost:5173"

注意：不要为了省事使用通配符（如*）来绕过 CORS 限制，也不要将 Ollama 暴露到公共互联网——这些都是排障捷径，但会带来严重的安全风险。只用 AIRI 需要的精确 origin。

校验通过但意识模块里没有模型

如果 provider 校验通过、但「意识」模块的模型列表为空，通常是 Ollama 尚未下载任何模型（ollama run <model>未执行过），或模型列表接口返回异常。回到终端先完成模型下载，再刷新设置页；必要时可在「意识」模块手动输入与 Ollama 官方一致的模型 ID。

从源码看 AIRI 的 Ollama 集成架构

AIRI 对 Ollama 的支持落在@proj-airi/provider-inference包的本地 provider 分组中，核心结构清晰：

• providerOllama 定义：负责配置 schema、思考模式映射、请求构造与校验器装配；
• provider 注册表：providerOllama与其他 40+ 个云/本地 provider 一起被注册为可移植定义，运行时再按需加载；
• Ollama 设置页面：落地 Base URL、思考模式、请求头与校验状态展示的 UI；
• OpenAI 兼容校验器：为 Ollama 复用了连通性、模型列表、聊天补全三类检查，这也是它无需 API Key 即可完成全链路验证的原因。

这套架构意味着：只要 Ollama 服务可达、模型已下载，AIRI 的聊天模块就能以完全本地化的方式工作，适合注重数据本地处理或希望脱离云端依赖的用户作为首选聊天提供者。

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手