【AI-27 React-13/Lesson98(2026-01-07)】Ollama 本地大模型部署与前端集成指南🤖

🤖 什么是 Ollama

Ollama 是一个强大的本地大模型部署工具，它让开发者可以轻松地在本地计算机上运行各种开源大语言模型（LLM）。与云端的 AI 服务（如 OpenAI GPT-4、Claude、Gemini 3.0+ 等）不同，Ollama 将模型完全部署在用户的本地设备上，无需联网即可使用，这为数据安全和隐私保护提供了极大的保障。

在当今的 AI 时代，开源大模型如雨后春笋般涌现，其中最具代表性的包括：

LLama3（羊驼）：Meta 开源的系列模型，性能优秀，社区活跃
Deepseek：深度求索开发的国产大模型，在代码生成等领域表现出色
Qwen（通义千问）：阿里巴巴开源的大模型，中文理解能力强

这些开源模型通常有不同的参数规模，从几百亿到几千亿不等。参数规模越大，模型能力通常越强，但对硬件的要求也越高。本地部署时，需要考虑 GPU、内存等硬件资源；而云端部署则需要租赁服务器和计算资源。

🔧 Ollama 的安装与基本使用

首先，你需要安装 Ollama。安装完成后，就可以通过命令行来管理和运行模型了。

验证安装

bash 复制代码

ollama --version

这条命令可以检查 Ollama 是否已正确安装，并显示当前版本号。

拉取模型

Ollama 提供了一个模型仓库，你可以从中拉取各种模型。以 Qwen2.5:0.5b 为例：

bash 复制代码

ollama pull qwen2.5:0.5b

这里的 qwen2.5:0.5b 是模型名称和标签，0.5b 表示参数规模为 5 亿。对于入门级用户，小参数模型是很好的选择，因为它们运行速度快，对硬件要求低。

你还可以拉取其他类型的模型，比如嵌入模型（Embedding Model）：

bash 复制代码

ollama pull dengcao/Qwen3-Embedding-8B:Q4_K_M

嵌入模型用于将文本转换为向量表示，常用于检索增强生成（RAG）等场景。

查看已安装的模型

bash 复制代码

ollama list

这条命令会列出所有本地已安装的模型及其信息。

运行模型

bash 复制代码

ollama run qwen2.5:0.5b

运行模型后，你可以直接在命令行中与模型对话。更重要的是，Ollama 会在后台启动一个 API 服务，默认监听 11434 端口，这个服务提供了与 OpenAI API 兼容的接口，方便我们通过代码调用。

📡 Ollama API 服务详解

Ollama 的 11434 端口提供了标准的 OpenAI 兼容 API，其中最常用的就是 /v1/chat/completions 接口。让我们来看一个简单的示例：

javascript 复制代码

const OLLAMA_URL = 'http://localhost:11434/v1/chat/completions';

const headers = {
  'Content-Type': 'application/json',
}

const data = {
  model: 'qwen2.5:0.5b',
  messages: [
    {
      role: 'user',
      content: '你好，你是谁啊？'
    },
  ],
}

fetch(OLLAMA_URL, {
  method: 'POST',
  headers,
  body: JSON.stringify(data),
})
  .then(res => res.json())
  .then(data =>
    console.log(data.choices[0].message))
  .catch(err => console.error('Error:', err))

这个示例使用原生的 fetch API 调用 Ollama 服务。请求体中包含：

model：指定使用的模型
messages：对话历史数组，每个消息包含 role（角色，可以是 user、assistant、system）和 content（内容）

💻 构建 React + Vite 聊天应用

接下来，让我们创建一个完整的前端聊天应用，使用 React + Vite 作为技术栈，配合 TailwindCSS 进行样式开发。

项目初始化

首先，创建一个新的 Vite 项目：

bash 复制代码

npm init vite

按照提示选择：

项目名称：ollama-chat
框架：React
语言：JavaScript

然后安装依赖，包括 axios 用于 HTTP 请求：

bash 复制代码

cd ollama-chat
pnpm i axios

集成 TailwindCSS

TailwindCSS 是一个实用优先的 CSS 框架，可以极大提高开发效率。安装和配置步骤如下：

安装依赖：

bash 复制代码

pnpm install tailwindcss @tailwindcss/vite

配置 vite.config.js：

javascript 复制代码

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    react(),
    tailwindcss()
  ],
})

在 src/index.css 中引入 TailwindCSS：

css 复制代码

@import "tailwindcss";

现在你就可以在项目中使用 TailwindCSS 的类名来构建 UI 了！

🔌 API 封装与自定义 Hooks

为了代码的可维护性和复用性，我们应该将 API 调用逻辑封装起来。

封装 Ollama API

创建 src/api/ollamaApi.js 文件：

javascript 复制代码

import axios from 'axios';

const ollamaApi = axios.create({
  baseURL: 'http://localhost:11434/v1',
  headers: {
    'Authorization': 'Bearer ollama',
    '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[0].message.content;
  } catch(err) {
    console.error('ollama 请求失败')
  }
}

这里我们使用了 axios.create 创建了一个实例，设置了基础 URL 和默认请求头。chatCompletions 函数接收消息数组，调用 API 并返回模型的回复内容。

创建自定义 Hook

创建 src/hooks/useLLM.js 文件，用于管理聊天状态：

javascript 复制代码

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 = () => {}
  const resetChat = () => {}

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

这个 Hook 管理了消息列表、加载状态、错误信息，并提供了发送消息和重置聊天的函数框架。

🎨 构建聊天界面

在 src/App.jsx 中，我们使用 TailwindCSS 构建了一个简洁美观的聊天界面：

javascript 复制代码

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

export default function App() {
  const [inputValue, setInputValue] = useState('');
  const { messages, loading } = useLLM();
  const handleSend = () => {}

  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]">
        1111
      </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"
            className="bg-blue-600 text-white px-4 py-2 rounded-lg hover:bg-blue-700 transition disabled:bg-gray-400"
            disabled={loading || !inputValue.trim()}
          >
            按钮
          </button>
        </div>
      </form>
    </div>
  )
}

这个界面包含：

一个容器 div，设置了灰色背景和居中布局
一个白色的聊天区域卡片，有圆角和阴影
一个输入表单，包含文本输入框和发送按钮
使用了 TailwindCSS 的各种类名来设置样式、布局和交互效果

🔐 为什么选择本地部署？AI 安全考量

在企业级应用中，AI 安全是一个至关重要的问题。想象一下，如果你把设计稿交给云端的 LLM 生成前端代码，或者使用像 Cursor 这样的工具把整个代码库上传，敏感信息可能会面临泄露的风险。

那么如何解决 AI 安全问题呢？有两个主要方案：

使用自家 AI 产品或模型：由公司内部团队开发和维护的 AI 服务
自己部署大模型：像 Ollama 这样，在本地或私有服务器上部署开源模型

本地部署的优势在于：

数据完全在本地，不会上传到第三方服务器
不受网络连接限制，可以离线使用
可以根据需求自由调整和优化模型
长期来看成本更低，特别是对于高频使用场景

🚀 总结

Ollama 为我们打开了本地大模型应用的大门。通过 Ollama，我们可以轻松地在本地部署 Qwen、Deepseek、LLama3 等优秀的开源模型，并通过 11434 端口的 OpenAI 兼容 API 进行调用。结合 React + Vite + TailwindCSS，我们可以快速构建出功能完整、界面美观的聊天应用。

更重要的是，本地部署为数据安全提供了坚实的保障，特别适合企业级应用和对隐私敏感的场景。随着开源大模型技术的不断进步，本地 AI 应用的前景将会越来越广阔！