需替换OnlyAI本地服务模型文件以升级性能：一、确认models/下当前模型路径及版本；二、下载匹配硬件的新版模型包并解压；三、停服务、备份旧模型、复制新模型、校验哈希；四、更新config.yaml中default_model和model_path字段；五、启动服务并验证日志与API响应。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您已部署OnlyAI本地服务，但希望更换为更新版本的模型文件以获得更强性能或新增能力，则需执行模型文件替换操作。以下是完成该任务的具体步骤：
一、确认模型存放路径与当前版本
OnlyAI本地服务默认将模型文件存放在固定目录中，替换前必须准确定位当前模型位置并核对版本兼容性，避免因路径错误或版本不匹配导致服务启动失败。
1、打开OnlyAI服务所在根目录，进入 models/ 子文件夹；
2、检查该目录下是否存在以模型名称命名的子文件夹（如 qwen2-7b/ 或 llama3-8b-instruct/）；
3、进入对应模型子文件夹，查看是否存在 config.json 与 model.safetensors（或 pytorch_model.bin）等核心文件；
4、比对模型文件夹内 README.md 或 VERSION 文件中的版本号，确认是否为待更新目标版本。
二、下载新版本模型文件包
OnlyAI支持从官方模型仓库或可信镜像源获取标准格式模型，必须确保下载的模型结构与OnlyAI当前加载逻辑一致，否则无法识别。
1、访问OnlyAI官方模型发布页（如 https://models.onlyai.dev/qwen2-7b-v2.1）或指定镜像站；
2、选择与您硬件环境匹配的量化版本（如 Q4_K_M 或 FP16），注意显存与磁盘空间限制；
3、点击下载按钮获取完整压缩包（通常为 qwen2-7b-v2.1.Q4_K_M.gguf.zip 格式）；
4、使用解压工具（如7-Zip）将压缩包内容解压至临时文件夹，确保解压后顶层目录结构包含 gguf 或 safetensors 文件且无嵌套冗余层级。
三、安全替换模型文件
直接覆盖原模型可能导致服务异常，应采用原子化替换方式：先停用服务、再备份旧模型、最后导入新模型并校验完整性。
1、在命令行中执行 ollama ps（若集成Ollama）或 systemctl stop onlyai-server（若为Linux系统服务）停止当前运行实例；
统一LLM网关 - 一个API对接70+AI模型，使用单一API密钥即可调用GPT、Claude、Gemini、Qwen、Deepseek、Grok等主流模型。
2、将原模型文件夹重命名为 qwen2-7b.backup（保留原始路径，仅修改名称）；
3、将解压后的新模型文件夹（如 qwen2-7b-v2.1）复制到 models/ 目录下；
4、进入新模型文件夹，运行 sha256sum model.safetensors（或对应主权重文件），比对官网公布的哈希值是否一致。
四、更新配置文件指向新模型
OnlyAI通过配置文件指定默认加载模型，若未同步更新配置项，服务重启后仍将加载旧模型路径或报错缺失模型。
1、打开 config.yaml 或 settings.json（取决于部署模式）；
2、定位到 default_model: 字段，将其值修改为新模型文件夹名称（不含路径，如 qwen2-7b-v2.1）；
3、检查 model_path: 是否仍指向旧路径，如有则同步更正为 ./models/qwen2-7b-v2.1/；
4、保存文件，确保编码为UTF-8且无BOM头，避免解析失败。
五、验证新模型加载状态
服务启动后需实时确认模型是否成功初始化，包括参数加载、设备绑定及推理响应，不可仅依赖进程存活状态。
1、执行 ollama run qwen2-7b-v2.1（如使用Ollama集成）或 python app.py --model qwen2-7b-v2.1 启动服务；
2、观察控制台输出，确认出现 Loading model from ./models/qwen2-7b-v2.1/ 类似日志；
3、等待日志中出现 Model loaded successfully on CUDA:0（或 on CPU）提示；
4、向API端点（如 http://localhost:3000/v1/chat/completions）发送测试请求，检查返回中 model 字段是否为新版本标识。
