大模型应用开发 / 系统课时

接入本地聊天界面

接入本地聊天界面

学习目标

完成本课后,你将能够:

  • 说明聊天界面连接 Ollama 所需配置
  • 区分模型服务、界面和会话存储职责
  • 设计模型白名单、用户权限和文件上传边界
  • 验证流式响应、历史和错误展示

聊天界面不是 Ollama 的一部分

Ollama 提供模型运行和 API。Web 聊天界面通常负责:

  • 用户登录
  • 会话列表
  • Markdown 渲染
  • 文件上传
  • 模型选择
  • 消息持久化
  • 流式取消
  • 权限和审计

两者可以部署在同机或不同主机,但安全边界必须清晰。

最小连接参数

界面或后端通常需要:

text
OLLAMA_BASE_URL=http://ollama:11434
DEFAULT_MODEL=gemma3:1b
REQUEST_TIMEOUT_SECONDS=<TIMEOUT>
ALLOWED_MODELS=gemma3:1b,<OTHER_MODEL>

变量名称由具体聊天项目定义,不能把示例名称当作所有软件的通用配置。接入第三方项目时必须查阅其官方文档。

推荐部署链路

text
浏览器
→ 聊天应用
→ 应用后端
→ Ollama

浏览器不直接访问 Ollama,可以让后端统一处理认证、模型白名单、会话和日志。Docker 网络中,聊天应用应使用服务名访问 Ollama,而不是容器内的 localhost。

模型发现

后端可调用:

bash
curl --fail --silent --show-error http://ollama:11434/api/tags

预期响应结构:

json
{
  "models": [
    {
      "name": "<MODEL>",
      "size": 0,
      "details": {
        "parameter_size": "<SIZE>",
        "quantization_level": "<QUANTIZATION>"
      }
    }
  ]
}

界面不应把所有本地模型自动开放给所有用户。应与业务白名单和权限取交集。

会话存储

建议保存:

  • 会话 ID 和用户 ID
  • 模型完整名称
  • 系统提示词版本
  • 用户与助手消息
  • 工具调用和状态
  • 取消或失败标记
  • Token 和耗时
  • 创建与更新时间

不建议默认永久保存完整 thinking、Base64 图片和敏感文档内容。

流式体验

界面应处理:

  • 首个数据块加载状态
  • Markdown 增量渲染
  • 停止按钮
  • 网络断开重连提示
  • 回答未完成标记
  • 最终 Token 和耗时
  • 代码块复制
  • 大输出虚拟滚动或折叠

代理缓冲会破坏实时体验,应在部署层关闭。

文件上传边界

文件上传不是“把文件路径交给模型”。后端需要:

  1. 校验类型和大小。
  2. 隔离临时目录。
  3. 解析文本或图片。
  4. 做权限和病毒检查。
  5. 控制进入上下文的内容。
  6. 删除临时文件。
  7. 对长期文档建立 RAG 索引。

禁止用户通过路径参数读取服务器任意文件。

基础权限

至少实现:

  • 登录认证
  • 模型白名单
  • 每用户并发限制
  • 会话所有权校验
  • 上传大小限制
  • 管理员与普通用户分离
  • 日志访问权限
  • 数据保留与删除

默认 Ollama 端口应只对聊天后端或受控内网开放。

验收清单

  • 用户能选择允许的模型。
  • 不允许模型不会出现在列表。
  • 流式回答可取消。
  • 刷新页面后历史可恢复。
  • 失败消息不会显示为成功回答。
  • 其他用户无法访问会话。
  • 上传文件受类型和大小限制。
  • 服务日志不记录敏感全文。

本课练习

练习 1:设计聊天架构

任务目标:明确组件职责。输入或初始条件:准备浏览器、后端和 Ollama。实现要求:画出认证、请求和数据流。验收条件:浏览器不能直接绕过后端访问模型服务。

练习 2:实现模型白名单

任务目标:限制模型使用。输入或初始条件:Ollama 本地有多个模型。

实现要求:对 /api/tags 结果做权限过滤。验收条件:未批准模型无法通过修改请求调用。

练习 3:测试会话隔离

任务目标:防止跨用户访问。输入或初始条件:创建两个测试用户。实现要求:尝试访问对方会话。验收条件:服务端返回拒绝,不能只在前端隐藏。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

接入本地聊天界面

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通