UI Docs

Appearance

Ollama Node ​

ollama-node 是一个 Node.js 后端项目，主要负责 AI 对话服务接入、模型分发、用户鉴权、文件处理和后台业务接口输出。

项目定位 ​

  • 面向 AI 对话产品的后端服务
  • 承载模型调用、接口聚合和业务数据管理
  • 作为前端聊天项目和后台系统的服务支撑层

核心能力 ​

  • 模型能力：支持本地 Ollama、OpenAI 兼容协议、Gemini 等模型接入与分发
  • 对话能力：提供聊天、会话、模型、RAG 相关接口
  • 用户能力：提供登录、注册、权限、角色和菜单等后台常见接口
  • 文件能力：支持文件记录、对象存储和图片处理相关能力

技术栈 ​

  • Node.js
  • Express
  • MongoDB
  • Mongoose
  • JWT
  • Axios

适合承载的场景 ​

  • AI 对话后端
  • 多模型统一接入层
  • 带权限体系的业务 API 服务
  • 聊天前端配套服务端项目

技术亮点 ​

1. 大模型分发层做了清晰解耦 ​

  • 模型能力不是写死在接口里，而是拆成“注册表 + 解析器 + 分发器 + handler”
  • 新增模型时，通常只需要补模型注册信息和对应 handler
  • 文本模型、图像模型、视频模型走的是统一入口，但内部执行链路彼此独立

2. 同时兼容多种模型协议 ​

  • 本地 Ollama 走本地服务协议
  • OpenAI、DeepSeek、部分 Gemini 能力走 OpenAI 兼容协议
  • Gemini 原生思考链和图像能力又单独走原生协议处理
  • 这意味着后端不是简单代理，而是做了一层真正的协议适配

3. 图文上下文做了模型感知处理 ​

  • 不是所有模型都直接接收同一份消息结构
  • 服务端会先判断当前模型是否支持 vision
  • 对支持视觉的模型，再把 Markdown 图片转换成不同协议需要的结构
  • 对不支持视觉的模型，会在入口阶段直接拦掉图片上下文，避免无效请求

4. SSE 输出做了统一事件协议 ​

  • 服务端没有把不同模型的流直接原样透传给前端
  • 而是统一整理成 content、reasoning、progress、image、loading、error、done 等事件
  • 这样前端只需要认这一套协议，就能兼容多模型流式输出

5. 对话、会话、权限是完整串起来的 ​

  • 聊天请求会先校验当前会话是否属于当前用户
  • 会话和消息分别落表，便于历史记录和后续扩展
  • 菜单、角色、管理员初始化也做了单独接口，具备中后台系统基础能力

6. 图片结果做了对象存储归一化 ​

  • 模型返回的图片结果不会长期以内联 base64 方式保留
  • 服务端会把结果上传到对象存储，再回写成可访问地址
  • 这样更适合历史消息存储和前端渲染

技术难点 ​

1. 模型协议差异非常大 ​

  • 同样是“聊天接口”，不同模型返回的数据结构、流式格式、图像输入方式都不同
  • 后端现在已经做了统一收口，但这块仍然是维护成本最高的区域之一

2. 图文上下文需要按模型动态转换 ​

  • OpenAI 兼容协议和 Gemini 原生协议对图片输入格式完全不同
  • 有的模型吃 image_url
  • 有的模型需要把远程图片先下载，再转成 base64 再发送
  • 这部分不是普通 CRUD 代码，技术含量比较高

3. 流式输出不只是“把文本吐出去” ​

  • 不同模型的流式事件边界并不统一
  • 有的返回文本增量
  • 有的返回思考链
  • 有的还带图片和进度事件
  • 要统一成前端能稳定消费的 SSE 协议，服务端做了额外的解析和重组

4. 鉴权和权限只是基础版完整，不是最终形态 ​

  • 当前 JWT、角色、菜单、管理员初始化这条链路已经可用
  • 但如果继续往更复杂的企业权限体系演进，还会涉及按钮级权限、资源级权限和更细粒度的 RBAC/ABAC

项目特点 ​

  • 多模型统一接入与分发
  • OpenAI 兼容协议与本地 Ollama 并行支持
  • 图文上下文按模型能力动态转换
  • SSE 统一事件协议
  • 会话、消息、权限、菜单一体化后端能力

扩展方向 ​

  • 短信验证码登录
  • 模型注册表扩展
  • 图片生成与图片处理链路
  • RAG 相关接口接入