从零构建本地AI应用：React与Ollama全栈开发实战

2026年1月17日 17:39

博客开篇：为什么选择本地大模型开发？

在当前的AI浪潮中，OpenAI等云端API虽然强大，但存在数据隐私、Token成本和网络延迟的问题。Ollama 的出现，让开发者可以在本地轻松部署开源大模型（如Qwen、Llama 3等）。结合前端框架（如React），我们可以构建完全私有、低成本的AI应用。

本博客将带你从环境搭建到代码实现，一步步构建一个基于 React 和 Ollama 的聊天应用，并深入剖析其中的技术细节。

第一部分：环境与基础架构

1.1 Ollama 核心原理

Ollama 是一个在本地运行大型语言模型的工具。它通过一个简单的命令行接口，让开发者可以拉取（Pull）、运行（Run）和管理模型。

核心命令：
- ollama pull qwen2.5:0.5b：拉取特定版本的千问模型。
- ollama run qwen2.5:0.5b：启动模型。
- 端口服务： Ollama 默认在 11434 端口提供服务，且提供了兼容 OpenAI 格式的 /v1/chat/completions 接口。

1.2 项目初始化

我们需要一个 React 项目来作为前端界面。使用 Vite 或 Create React App 初始化项目，并安装必要的依赖（如 axios 用于 HTTP 请求）。

第二部分：后端通信层（API 模块）

这是应用的“神经系统”，负责前端与本地大模型的对话。

2.1 代码逻辑解析

在提供的代码中，ollamaApi.js 文件负责创建与 Ollama 服务的连接。

import axios from 'axios';

// 创建 axios 实例
const ollamaApi = axios.create({
  baseURL: 'http://localhost:11434/v1', // 指向本地 Ollama 服务
  headers: {
    'Authorization': 'Bearer ollama', // 注意：Ollama 的固定 Token
    'Content-Type': 'application/json',
  }
});

// 封装聊天请求函数
export const chatCompletions = async (messages) => {
  try {
    const response = await ollamaApi.post('/chat/completions', {
      model: 'qwen2.5:0.5b', // 指定模型名称
      messages, // 对话历史
      stream: false, // 关闭流式输出（简化处理）
      temperature: 0.7, // 控制生成文本的随机性
    });
    return response.data.choices.message.content;
  } catch(err) {
    console.error('ollama 请求失败');
  }
}

2.2 技术点详解

Axios 封装： 使用 axios.create 创建实例，统一管理 baseURL 和 headers，避免在每个请求中重复配置。
兼容性接口： Ollama 采用了 OpenAI 的 API 规范，这意味着如果你的后端换成 OpenAI，前端代码几乎不需要修改。
请求参数：
- messages: 这是一个数组，包含 role (system/user/assistant) 和 content。注意： 必须传入完整的对话历史，模型才能理解上下文。
- temperature: 值越低越确定，越高越有创造性。

🧠 答疑解惑：易错点与排查

问题：跨域错误 (CORS) 或网络连接失败
- 原因： 前端运行在 localhost:3000，而 Ollama 服务运行在 localhost:11434。虽然同源策略通常允许不同端口，但如果 Ollama 服务未启动，会报 ECONNREFUSED。
- 解决方案：
  1. 确保 Ollama 服务已启动（终端运行 ollama serve 或直接运行模型）。
  2. 检查防火墙设置。
  3. 在开发环境中，如果遇到严格的 CORS 限制，可以考虑使用 Vite 的代理配置（Proxy）。
问题：401 Unauthorized 错误
- 原因： 虽然 Ollama 本地部署通常不需要复杂的鉴权，但根据代码规范，它要求 Header 中必须包含 Authorization: Bearer ollama。
- 解决方案： 确保在请求头中正确设置了该字段。
问题：模型未找到 (Model not found)
- 原因： 代码中写死了 qwen2.5:0.5b，但本地未下载该模型。
- 解决方案： 运行 ollama pull qwen2.5:0.5b，或者修改代码中的 model 字段为你本地已有的模型（如 llama3）。

💼 面试模拟：API 层设计

面试官： “在封装 API 时，为什么要使用 Axios 实例而不是直接使用 axios.post？”
候选人：

统一管理： 如果 baseURL 变更（例如从开发环境切换到生产环境），只需修改实例配置，无需修改每个请求。
拦截器： 实例可以添加请求拦截器（自动加 Token）和响应拦截器（统一错误处理）。
复用性： 可以创建多个实例对应不同的后端服务。

第三部分：前端状态管理（Hooks 模块）

3.1 代码逻辑解析

useLLM.js 文件是一个自定义 Hook，用于管理聊天应用的状态。

import { useState } from 'react';
import { chatCompletions } from '../api/ollamaApi.js';

export const useLLM = () => {
  const [messages, setMessages] = useState([
    { role: 'user', content: '你好' },
    { role: 'assistant', content: '你好，我是qwen2.5 0.5b 模型' }
  ]);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  // 发送消息逻辑
  const sendMessage = async (userMessage) => {
    // 1. 更新UI：添加用户消息
    const newMessages = [...messages, { role: 'user', content: userMessage }];
    setMessages(newMessages);
    setLoading(true);
    setError(null);

    try {
      // 2. 调用API
      const botResponse = await chatCompletions(newMessages);
      // 3. 更新UI：添加机器人回复
      setMessages(prev => [...prev, { role: 'assistant', content: botResponse }]);
    } catch (err) {
      setError('请求失败，请重试');
    } finally {
      setLoading(false);
    }
  };

  const resetChat = () => {
    setMessages([]);
  };

  return { messages, loading, error, sendMessage, resetChat };
};

3.2 技术点详解

状态设计： 使用 messages 数组存储对话历史，loading 控制按钮状态，error 处理异常。
闭包与异步： 在 sendMessage 中，我们使用了函数式更新 setMessages(prev => [...prev, ...]) 来确保获取到最新的状态，避免闭包陷阱。
错误边界： 使用 try-catch 捕获 API 异常，并通过 setError 反馈给 UI。

🧠 答疑解惑：易错点与排查

问题：机器人回复总是“上一轮”的内容
- 原因： 这是一个经典的 State 闭包问题。如果你在调用 API 前没有正确更新 messages，或者在调用 API 时传入的是旧的 messages 快照。
- 解决方案：
  - 方案 A： 如上面的代码所示，先构造新的消息数组 newMessages，传给 API，成功后再更新 State。
  - 方案 B： 使用 useRef 保存最新的消息列表，或者在 setMessages 的回调中处理后续逻辑（虽然 React 18 严格模式下可能执行两次渲染，但逻辑上应保证幂等性）。
问题：输入框无法输入或按钮一直禁用
- 原因： 逻辑错误导致 loading 状态未重置。
- 解决方案： 确保 try-catch-finally 结构完整。无论成功或失败，finally 块中必须将 loading 设为 false。

💼 面试模拟：React Hooks

面试官： “在 sendMessage 函数中，为什么在 setMessages 之后立即调用 API，传入的 messages 可能不是最新的？如何解决？”
候选人：
React 的 setState 是异步的。在 setMessages 调用后，messages 变量的值在当前函数作用域内并没有立即改变。如果直接传 messages 给 API，会丢失刚刚添加的用户消息。
解决方法：

预计算： 像代码中那样，先用 const newMessages = [...messages, userMsg] 计算出新数组，传给 API，然后 setMessages(newMessages)。
函数式更新： 如果逻辑复杂，可以使用 useRef 来维护一个可变的引用。

第四部分：视图层（UI 组件）

4.1 代码逻辑解析

App.jsx 是应用的主组件，负责展示和用户交互。

import { useEffect, useState } from 'react';
import { useLLM } from './hooks/useLLM.js';

export default function App() {
  const [inputValue, setInputValue] = useState('');
  const { messages, loading, sendMessage } = useLLM(); // 使用自定义 Hook

  const handleSend = (e) => {
    e.preventDefault();
    if (!inputValue.trim()) return;
    sendMessage(inputValue); // 调用 Hook 中的逻辑
    setInputValue(''); // 清空输入框
  };

  // 页面挂载时的初始化逻辑（可选）
  useEffect(() => {
    // 例如：加载历史记录
  }, []);

  return (
    <div className="min-h-screen bg-gray-50 flex flex-col items-center py-6 px-4">
      <div className="w-full max-w-[800px] bg-white rounded-lg shadow-md flex flex-col h-[90vh] max-h-[800px]">
        {/* 聊天内容区域 */}
        <div className="flex-1 p-4 overflow-y-auto">
          {messages.map((msg, idx) => (
            <div key={idx} className={`mb-4 p-3 rounded-lg max-w-xs ${msg.role === 'user' ? 'bg-blue-100 ml-auto' : 'bg-gray-100'}`}>
              {msg.content}
            </div>
          ))}
        </div>
      </div>
      
      <form className="p-4 border-t" onSubmit={handleSend}>
        <div className="flex gap-2">
          <input
            type="text"
            value={inputValue}
            onChange={e => setInputValue(e.target.value)} 
            placeholder="输入消息....按回车发送"
            disabled={loading} 
            className="flex-1 px-4 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500"
          />
          <button 
            type="submit"
            disabled={loading || !inputValue.trim()}
            className="bg-blue-600 text-white px-4 py-2 rounded-lg hover:bg-blue-700 transition"
          >
            {loading ? '思考中...' : '发送'}
          </button>
        </div>
      </form>
    </div>
  );
}

4.2 技术点详解

受控组件： input 的 value 绑定到 inputValue，通过 onChange 更新状态，保证 UI 与 State 一致。
表单处理： 使用 onSubmit 处理表单提交，并调用 e.preventDefault() 阻止页面刷新。
条件渲染： 根据 loading 状态禁用按钮和改变按钮文本，防止重复提交。

🧠 答疑解惑：易错点与排查

问题：按下回车键页面刷新了
- 原因： <form> 标签的默认行为是 onSubmit 触发页面跳转。
- 解决方案： 在 handleSend 函数的第一行加上 e.preventDefault();。
问题：聊天记录滚动条没有自动到底部
- 原因： DOM 更新后，容器的 scrollTop 没有自动调整。
- 解决方案： 使用 useRef 获取聊天容器的 DOM 引用，在 useEffect 中监听 messages 变化，并设置 container.scrollTop = container.scrollHeight。

💼 面试模拟：UI 与用户体验

面试官： “如何优化这个聊天界面的用户体验（UX）？”
候选人：

流式响应： 当前代码设置 stream: false，用户需要等待模型生成完所有文本才能看到结果。开启 stream: true 可以实现逐字输出的效果，体验更像真人打字。
加载状态： 除了按钮禁用，聊天区域可以增加一个“机器人正在思考...”的 Typing 动画。
错误重试： 当 API 调用失败时，UI 应该提供一个“重试”按钮，而不是仅仅显示错误文本。

第五部分：进阶与优化

5.1 流式传输 (Streaming)

目前的代码是等待模型生成完所有内容后一次性返回。为了实现类似 ChatGPT 的打字机效果，我们需要开启流式传输。

原理： 设置 stream: true，后端会以 text/event-stream 格式分块传输数据。
实现： 在 chatCompletions 函数中，需要使用 fetch API 替代 Axios（因为 Axios 对流式处理支持较弱），并读取 ReadableStream。

5.2 上下文管理

qwen2.5:0.5b 这种 0.5B 参数的模型内存有限。如果对话过长，模型会“忘记”开头的内容，或者出现显存溢出。

解决方案： 实现一个简单的上下文截断逻辑，只保留最近的 N 轮对话传给模型。

5.3 模型切换

可以扩展 UI，让用户在界面上选择不同的本地模型（如从 qwen 切换到 llama3）。

博客结语

通过这篇博客，我们完成了一个从本地大模型部署到前端全栈应用的开发流程。这不仅是一个技术Demo，更是理解现代AI应用架构的基石。

核心收获：

Ollama 是本地AI的基石，它让大模型触手可及。
React Hooks 极大地简化了状态管理的复杂度。
前后端分离 的思想依然适用，即使是与本地服务通信。

希望这篇教程能帮助你在本地AI开发的道路上更进一步！

阅读视图

博客开篇：为什么选择本地大模型开发？

第一部分：环境与基础架构

1.1 Ollama 核心原理

1.2 项目初始化

第二部分：后端通信层（API 模块）

2.1 代码逻辑解析

2.2 技术点详解

🧠 答疑解惑：易错点与排查

💼 面试模拟：API 层设计

第三部分：前端状态管理（Hooks 模块）

3.1 代码逻辑解析

3.2 技术点详解

🧠 答疑解惑：易错点与排查

💼 面试模拟：React Hooks

第四部分：视图层（UI 组件）

4.1 代码逻辑解析

4.2 技术点详解

🧠 答疑解惑：易错点与排查

💼 面试模拟：UI 与用户体验

第五部分：进阶与优化

5.1 流式传输 (Streaming)

5.2 上下文管理

5.3 模型切换

博客结语