大模型应用开发 / 系统课时
接入本地聊天界面
接入本地聊天界面
学习目标
完成本课后,你将能够:
- 说明聊天界面连接 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 和耗时
- 代码块复制
- 大输出虚拟滚动或折叠
代理缓冲会破坏实时体验,应在部署层关闭。
文件上传边界
文件上传不是“把文件路径交给模型”。后端需要:
- 校验类型和大小。
- 隔离临时目录。
- 解析文本或图片。
- 做权限和病毒检查。
- 控制进入上下文的内容。
- 删除临时文件。
- 对长期文档建立 RAG 索引。
禁止用户通过路径参数读取服务器任意文件。
基础权限
至少实现:
- 登录认证
- 模型白名单
- 每用户并发限制
- 会话所有权校验
- 上传大小限制
- 管理员与普通用户分离
- 日志访问权限
- 数据保留与删除
默认 Ollama 端口应只对聊天后端或受控内网开放。
验收清单
- 用户能选择允许的模型。
- 不允许模型不会出现在列表。
- 流式回答可取消。
- 刷新页面后历史可恢复。
- 失败消息不会显示为成功回答。
- 其他用户无法访问会话。
- 上传文件受类型和大小限制。
- 服务日志不记录敏感全文。
本课练习
练习 1:设计聊天架构
任务目标:明确组件职责。输入或初始条件:准备浏览器、后端和 Ollama。实现要求:画出认证、请求和数据流。验收条件:浏览器不能直接绕过后端访问模型服务。
练习 2:实现模型白名单
任务目标:限制模型使用。输入或初始条件:Ollama 本地有多个模型。
实现要求:对 /api/tags 结果做权限过滤。验收条件:未批准模型无法通过修改请求调用。
练习 3:测试会话隔离
任务目标:防止跨用户访问。输入或初始条件:创建两个测试用户。实现要求:尝试访问对方会话。验收条件:服务端返回拒绝,不能只在前端隐藏。
按自己的节奏,确认真正理解。