# BCY-LLM **Repository Path**: BraveCao/BCY-LLM ## Basic Information - **Project Name**: BCY-LLM - **Description**: Apple Silicon 原生本地模型工作台:MLX / GGUF 双运行时、模型库与下载队列、OpenAI 兼容推理服务 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-09 - **Last Updated**: 2026-11-09 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # BCY-LLM BCY-LLM 是面向 Apple Silicon Mac 的原生本地模型工具。本阶段提供可运行的模型管理、GGUF/MLX 下载队列、本地模型库与中英文界面设置。模型目录会直接显示每个仓库的下载状态和进度,并可在详情页暂停、恢复、取消、重试或定位已完成的模型文件;下载队列可以删除单条或批量清理终态历史,已安装模型不会随历史记录删除。 ## 系统要求 - Apple Silicon Mac - macOS 14 或更高版本 - Xcode Command Line Tools(包含 Swift 6 工具链) ## 构建、测试与运行 ```bash cd BCY-LLM swift build swift test swift run BCYLLM ``` 清理构建后可执行完整回归: ```bash swift package clean swift build swift test ./script/build_and_run.sh --verify ``` 如需执行实时 Provider 元数据检查(会访问 Hugging Face 和 ModelScope): ```bash BCY_LIVE_PROVIDER_TESTS=1 swift test --filter LiveProviderTests ``` 如需运行真实 GGUF embedding 子进程测试(需要本机已有 embedding `.gguf` 和对应 `llama-server`): ```bash BCY_LIVE_GGUF_EMBEDDING_MODEL_PATH=/path/to/embedding.gguf \ BCY_LLAMA_SERVER_PATH=/path/to/llama-server \ swift test --filter embedsWithRealGGUFEmbeddingRuntime ``` 真实 MLX embedding 测试需要一个能由 BCY-LLM 识别为“向量嵌入”的完整 MLX 模型目录: ```bash BCY_LIVE_MLX_EMBEDDING_MODEL_PATH=/absolute/path/to/mlx-embedding-model \ swift test --filter NativeMLXEmbeddingRuntimeTests.embedsWithRealLocalModel ``` 发行前可以用同一个脚本执行已配置的真实 MLX/GGUF 文本和 embedding 门禁。至少设置一个模型路径;GGUF 默认使用当前 `dist/BCY-LLM.app` 内置的 `llama-server`,也可以显式覆盖: ```bash BCY_LIVE_MLX_MODEL_PATH=/absolute/path/to/mlx-model \ BCY_LIVE_MLX_EMBEDDING_MODEL_PATH=/absolute/path/to/mlx-embedding-model \ BCY_LIVE_GGUF_MODEL_PATH=/absolute/path/to/model.gguf \ ./script/verify_live_models.sh ``` 已有真实文本模型和 embedding 模型登记到模型库后,可以进一步验证完整 App、LM Studio v1 模型管理 API、OpenAI-compatible 推理接口和重启恢复。该门禁会加载两个指定模型、发起真实文本与向量请求、终止并重新启动指定 App,再确认两个模型均已恢复;不会输出完整向量: ```bash BCY_LIVE_TEXT_MODEL_ID=YOUR_TEXT_MODEL_UUID \ BCY_LIVE_EMBEDDING_MODEL_ID=YOUR_EMBEDDING_MODEL_UUID \ ./script/verify_live_app.sh ``` 默认验证 `dist/BCY-LLM.app` 和 `127.0.0.1:1234`;可用 `BCY_LIVE_APP_PATH` 和 `BCY_LIVE_API_PORT` 覆盖。该脚本会真实退出并重启目标 App,只应在专门的发行验证会话中运行。 生成 DMG 时设置 `BCY_LIVE_RELEASE_TESTS=1` 会强制先运行该门禁;模型路径缺失、路径无效、运行时不可执行或真实生成失败时不会继续打包: ```bash BCY_LIVE_RELEASE_TESTS=1 \ BCY_LIVE_MLX_MODEL_PATH=/absolute/path/to/mlx-model \ BCY_LIVE_MLX_EMBEDDING_MODEL_PATH=/absolute/path/to/mlx-embedding-model \ BCY_LIVE_GGUF_MODEL_PATH=/absolute/path/to/model.gguf \ BCY_LLM_BUILD=1 \ ./script/build_dmg.sh ``` 也可以生成并启动使用 Release 构建的标准 `.app` 目录。该流程会下载固定版本 `llama.cpp b10225` 的官方 Apple Silicon 运行包,核对官方文件大小、SHA-256 和归档完整性后,将 `llama-server`、动态库及 MIT License 一起打包;不依赖用户安装 Homebrew: ```bash ./script/build_and_run.sh ``` 生成结果位于 `dist/BCY-LLM.app`。默认版本为 `0.1.0 (1)`;发布构建可显式提供版本和递增构建号: ```bash BCY_LLM_VERSION=0.1.0 BCY_LLM_BUILD=1 ./script/build_and_run.sh --verify ``` 仅构建和签名应用、不启动 GUI 时使用 `./script/build_and_run.sh --build-only`。DMG 和自动化发布流程使用该模式,避免在打包机器上启动应用。 每次标准 App 构建都会根据 `Package.resolved` 生成第三方合规材料,并在签名前验证:`Contents/Resources/THIRD-PARTY-NOTICES.txt` 汇总依赖来源与许可证全文,`Contents/Resources/ThirdPartyLicenses` 保留每个 SwiftPM 依赖和 `llama.cpp` 的原始 LICENSE/NOTICE,`Contents/Resources/BCY-LLM.spdx.json` 提供 SPDX 2.3 SBOM。`llama.cpp` 的固定版本、下载地址和归档 SHA-256 由 `script/llama_cpp_release.env` 统一提供。任何锁定依赖缺少普通许可证文件、许可证类型无法识别、SBOM 与 App 版本不一致或文件关系不完整时,构建和发布校验都会停止。 需要可复现的 SBOM 创建时间时,可以给构建命令设置非负整数 `SOURCE_DATE_EPOCH`;不设置时使用当前 UTC 时间。 ## DMG 发布包 生成可安装的本地测试 DMG 时,使用以下命令。它会先执行 Release 构建和 ad-hoc 签名校验,再创建 DMG、执行 `hdiutil verify`,并生成同名 `.sha256` 校验清单: ```bash BCY_LLM_VERSION=0.1.0 BCY_LLM_BUILD=1 ./script/build_dmg.sh ``` 产物默认位于 `dist/BCY-LLM-0.1.0-1.dmg`,镜像内含 `BCY-LLM.app` 与 `/Applications` 快捷方式。已经构建并验证过 `.app` 时,可跳过重新构建: ```bash ./script/build_dmg.sh --no-build ``` ### Developer ID 签名与 Apple 公证 发布脚本已经支持真实的 Developer ID 和 Apple 公证流程。商业构建需要先在登录钥匙串中安装组织的 `Developer ID Application` 证书,并通过 `xcrun notarytool store-credentials` 把公证凭据保存为钥匙串 profile。凭据不会写入源码、命令输出或产物。 设置以下环境变量后运行同一个 DMG 命令: ```bash BCY_LLM_SIGNING_IDENTITY="Developer ID Application: YOUR_ORGANIZATION (TEAM_ID)" \ BCY_LLM_NOTARY_PROFILE="BCY-LLM-notary" \ BCY_LLM_VERSION=0.1.0 \ BCY_LLM_BUILD=1 \ ./script/build_dmg.sh ``` 该流程会按嵌套代码顺序签名 `llama-server`、动态库、MLX Metal 库、主程序和 App,启用 Hardened Runtime 与安全时间戳;随后分别提交 App 和 DMG 公证、装订并验证票据,最后执行 Gatekeeper 检查并生成 SHA-256 清单。只设置公证 profile、签名身份不存在、签名不是 `Developer ID Application`、缺少 Team ID、未启用 Hardened Runtime 或公证状态不是 `Accepted` 时都会停止,不会生成“看似已发布”的产物。使用 `--no-build` 打包已经完成 Developer ID 签名的 App 时也必须再次提供相同签名身份,防止 DMG 被静默降级为本地测试包。 可以独立复核商业产物: ```bash ./script/verify_release.sh --notarized \ dist/BCY-LLM.app \ dist/BCY-LLM-0.1.0-1.dmg ``` 未设置上述环境变量时仍使用 ad-hoc 本地测试模式,不应作为对外商业发行包。 ### DMG 安装、升级与卸载门禁 可以在不写入 `/Applications` 的临时目录中验证真实 DMG 的挂载、首次安装、API 启动、覆盖升级、正常退出、运行时子进程清理和卸载: ```bash BCY_INSTALL_BASELINE_DMG_PATH="$PWD/dist/BCY-LLM-0.1.0-75.dmg" \ BCY_INSTALL_DMG_PATH="$PWD/dist/BCY-LLM-0.1.0-78.dmg" \ ./script/verify_install_lifecycle.sh ``` 上例使用当前已生成的 75→78 构建;后续发布时将两个路径替换为本地存在的基线包和目标包。也可以直接把目标 DMG 作为脚本参数传入;未提供参数或 `BCY_INSTALL_DMG_PATH` 时,脚本会读取 `dist/BCY-LLM.app/Contents/Info.plist` 的版本和构建号选择对应 DMG,不会回退到旧构建。门禁默认使用 `127.0.0.1:1234`,运行前应关闭占用该端口的 BCY-LLM 实例。脚本只会终止自己临时安装目录中的精确进程,并在退出时重复清理运行时子进程;可以通过 `BCY_INSTALL_API_PORT` 改用其他端口。当前仍是 ad-hoc 包时,这项验证只代表本机安装生命周期,不代表 Developer ID、公证或 Gatekeeper 商业发行资格。 ## 支持的模型 模型目录支持 Hugging Face 与 ModelScope 的匿名搜索,并默认显示更适合 Apple Silicon 的 MLX 结果;用户仍可切换到 GGUF 或全部支持格式,也可以直接打开 `https://huggingface.co/namespace/model`、`https://modelscope.cn/models/namespace/model`、`namespace/model` 或显式来源前缀。目录默认隐藏语音、视频生成等当前本地运行时明确不支持的任务,但会保留 `image-to-text`、`image-text-to-text` 和视觉问答 MLX 模型。搜索结果中的名称是实际下载仓库名称;详情同时显示模型卡声明的基础模型,不会把第三方转换或量化仓库伪装成官方发布。模型介绍按 Markdown 标题、段落、列表、引用和代码块排版,并可调用当前已加载的本地文本模型翻译为中文,译文只缓存在本机。选中的在线模型会在列表中保持高亮。本地模型详情会显示并可复制稳定的本地 API 模型 ID,可直接用于 JARVIS 等客户端的 `model` 字段;MLX 和 GGUF 文本模型默认使用模型声明的最大上下文,也支持在加载前手动选择更小的上下文。可选访问令牌只保存到 macOS Keychain。下载队列支持断点续传、暂停、恢复、取消、重试、校验和安装,任务状态保存在本地 SQLite 中并在启动时恢复。 - GGUF:常规 `.gguf` 文件,必须是当前运行时支持的 GGUF v2/v3,并通过有界元数据解析;标准 App 构建通过内置 `llama-server` 提供真实文本推理。GGUF 向量模型会按架构识别为 embedding,并通过独立的 `llama-server --embedding` 进程提供真实向量推理,不会被错误加载为文本模型。 - MLX:目录必须包含可读的 `config.json`、`tokenizer.json` 或 `tokenizer_config.json`,以及至少一个 `.safetensors` 权重文件。纯文本模型使用 `MLXLLM`,带受支持视觉配置的模型使用 `MLXVLM`;当前覆盖 Qwen 2/2.5/3 VL、Qwen 3.5/3.5 MoE、Gemma 3/4、Pixtral、Mistral 3、Idefics 3、PaliGemma、FastVLM、SmolVLM、LFM2 VL 和 GLM OCR 等依赖库已注册架构。混合模型既可处理纯文本,也可通过 OpenAI `content` 数组接收图片。 - Moshi MLX 实时语音:当前只支持官方 `kyutai/moshiko-mlx-q4` 三件套,即 Moshi Q4 权重、Mimi 权重和 SentencePiece 模型。运行前执行 `script/prepare_moshi_mlx.sh` 安装固定的 Python 3.12 + `moshi_mlx 0.3.0` 本地运行环境。加载时会用静音 PCM 帧完成原生编码、推理和解码自检;自检失败不会标记为可用。音频固定为 PCM16、24 kHz、单声道、1920 样本/帧,不包含 STT、TTS、录音、播放或聊天页面。 - Qwen2.5-Omni-3B 实时语音:只接受包含 Thinker、Talker、Token2Wav、全部索引分片和 `spk_dict.pt` 的官方完整 safetensors 产物。先执行 `script/prepare_qwen_omni_runtime.sh` 建立固定 Python 3.12 + PyTorch/Transformers MPS 环境,再执行 `script/download_qwen_omni_3b.sh` 下载并校验官方文件。输入为 PCM16、16 kHz、单声道、1600 样本/帧;客户端通过 `input_audio_buffer.commit` 提交回合,输出模型自身生成的用户转写、Thinker 生成期助手文字增量、助手完整文字和 PCM16、24 kHz 音频。模型加载后,“本地模型”详情页会显示 `spk_dict.pt` 实际提供的输出音色;选择按模型保存并从下一次实时会话开始传给官方 Talker,当前官方 3B 产物为 `Chelsie` 和 `Ethan`。不支持的音色、空音色字典和活动会话中的切换都会被明确拒绝。文字增量由 Transformers `TextIteratorStreamer` 从 Thinker 生成过程直接产生;Talker Codec Token 在生成期按官方低显存实现的 48 Token 核心、24 Token 左上下文和 12 Token 右上下文执行真实 Token2Wav 重叠解码,再输出 100 ms PCM 帧,不对完整文字或完整波形人工切片冒充模型级流式。回复期间继续接收下一轮麦克风帧;客户端发送 `input_audio_buffer.speech_started` 时立即取消当前 Thinker/Talker/Token2Wav 输出,`speech_stopped` 后可提交已保留的下一轮音频。该能力仍是“完整输入回合提交 + 流式输出”,不等同于 Moshi 的逐输入帧连续推理。未通过 Talker/Token2Wav 自检、分块连续性探针和真实插话门禁时不会标记为可用。 - Qwen3-Omni-30B-A3B-Instruct-4bit 实时语音:执行 `script/prepare_qwen3_omni_mlx_runtime.sh` 建立固定 Python 3.12 + `mlx-vlm` 运行环境。仅完整包含 Thinker 语言模型、Audio Tower、Talker、Code2Wav 和全部索引分片的 MLX 模型会被识别为实时语音模型。输入为 PCM16、16 kHz、单声道、1600 样本/帧,输出为模型原生生成的文字和 PCM16、24 kHz 音频;支持 `Aiden`、`Chelsie`、`Ethan`,单会话上下文限制为 16K。回复期间继续接收下一轮麦克风帧,`input_audio_buffer.speech_started` 会停止继续发布当前输出并触发插话事件。该实现是“完整输入回合提交 + Thinker/Talker 流式输出 + 可打断”的准全双工,不宣称模型在同一时刻持续听说;只有 Worker 启动时真实执行 Talker/Code2Wav 自检后才会发布能力。 外部导入只保存安全作用域引用和模型元数据,“移除引用”不会改动外部文件。由 BCY-LLM 下载并管理的模型会明确标记,用户确认后可以在模型详情中永久删除文件并回收磁盘空间;外部模型不提供文件删除入口。受管模型文件删除后,对应 completed 下载记录会在原目录可访问且确认目标不存在时自动失效,模型管理页和 LM Studio v1 下载 API 均可重新建立真实下载任务;外部磁盘暂时离线时不会误删记录或权限 bookmark。 ## 数据位置 模型库元数据存储在: ```text ~/Library/Application Support/BCY-LLM/library.sqlite3 ``` 下载队列数据库位于同目录的 `downloads.sqlite3`,模型文件默认位于 `Models` 子目录,也可以在“通用”中选择外部目录。模型库点击刷新时会扫描应用拥有的 `Models` 根目录,自动登记新放入的 MLX 模型目录和 GGUF 文件;外部目录仍需通过导入操作授予访问权限。 应用默认在回环地址 `http://127.0.0.1:1234` 提供本地推理和模型管理 API;可以在“通用”中查看状态、停止服务、修改端口并重新启动。需要让同一局域网内的 JARVIS 或其他客户端访问时,必须显式切换为“局域网”模式。该模式监听所有 IPv4 网络接口,并在每次启动时生成 256 位随机 Bearer 会话令牌;所有 API 请求都必须携带这个令牌。令牌不写入偏好设置、数据库或日志,停止或重启服务后立即失效。端口冲突不会阻止模型管理界面启动。 - `GET /v1/models` - `GET /v1/models/:model_id` - `GET /health` - `POST /v1/chat/completions` - `POST /v1/completions` - `POST /v1/responses` - `POST /v1/embeddings` - `GET /api/v0/models` 与 `GET /api/v0/models/:model` - `POST /api/v0/chat/completions` - `POST /api/v0/completions` - `POST /api/v0/embeddings` - `GET /api/v1/models` - `POST /api/v1/models/load` - `POST /api/v1/models/unload` - `POST /api/v1/models/download` - `GET /api/v1/models/download/status/:job_id` - `GET /v1/realtime`(WebSocket Upgrade,仅限已加载的原生实时语音模型) `/v1/models` 和 `/v1/models/:model_id` 除 OpenAI 标准字段外,还提供可忽略的 BCY-LLM 扩展字段;模型管理能力类型包括 `llm`、`vlm`、`embedding`、`reranker` 和 `realtime_voice`,并只报告运行时真实注册的能力。JARVIS 等客户端可以据此避免把模型用于错误任务,旧版 OpenAI 客户端会安全忽略这些额外字段。 局域网客户端使用 Mac 的实际局域网地址,并从“通用”页复制当前会话令牌: ```bash curl http://YOUR_MAC_LAN_IP:1234/v1/models \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' ``` 文本模型恢复时会同时恢复上次由运行时确认的 MLX 或 GGUF 上下文长度;显式卸载、模型失效或恢复失败会清理对应配置,避免 JARVIS 重连后静默切换回默认上下文。 服务默认只监听本机回环地址,不会意外暴露到局域网;局域网模式必须由用户显式开启,并在路由处理前对每个请求校验精确的 `Authorization: Bearer ...`。缺失或错误令牌返回 OpenAI 风格的 401 `authentication_error`,重复 `Authorization` header 会作为歧义请求拒绝。回环模式只接受 `127.0.0.1` 或 `localhost` 的单个 `Host` header,显式端口必须与服务端口一致;所有 POST 请求必须声明 `Content-Type: application/json`,缺失、重复或其他媒体类型会在进入推理层前拒绝。当前接口支持聊天消息、legacy 字符串 prompt、普通 JSON 响应和 `stream: true` 的 SSE 增量响应,供 JARVIS 等本地客户端调用;文本补全暂时只提供单候选(`n`/`best_of` 只能为 1),避免伪造未实现的多候选推理。客户端断开或用户停止服务时,会关闭全部活动连接并取消对应生成。请求 header 限制为 64 KiB、完整请求限制为 32 MiB,并有 15 秒读取空闲超时和 30 秒总读取超时;只接受 HTTP/1.1,不支持重复 `Content-Length` 或 `Transfer-Encoding`。Chat Completions 和 Responses API 的视觉输入支持最多 8 张 `data:image/jpeg|png|webp;base64,...` 图片,单张解码后不超过 20 MiB、16384 像素边长或 6400 万像素;本地运行时不读取 `file://` 路径,也不主动获取远程图片 URL。成功注册的文本、视觉、embedding、重排和实时语音实例会按持久化配置在下次启动时独立恢复;模型失效、子进程退出或恢复失败时会标记对应实例且不影响其它实例。多实例由统一注册表按模型 key 或 instance ID 精确路由,不设置加载内存预算,也不根据估算值拦截加载;如果新模型加载失败,对应运行状态会保持为未加载,并保留其它已加载实例。运行监控只显示 BCY-LLM 主进程及模型子进程的实际 RSS、CPU 和进程数。GGUF 后端仅监听随机回环端口,使用每次加载生成且不持久化的临时 Bearer Token;token 通过受控子进程环境传递,不出现在 `llama-server` 命令行,并由主应用负责启动、取消和卸载。请求支持 `max_tokens`、`max_completion_tokens`(二者不能冲突)、`temperature`、`top_p`、`top_k`、`min_p`、`repetition_penalty`、`presence_penalty`、`frequency_penalty`、非负整数 `seed` 和最多四个 `stop` 文本序列。`seed` 的统一范围为 0 至 2147483647;相同模型、提示词和采样参数可用于可重复的 JARVIS 回归测试,省略时继续使用随机采样。Chat Completions 支持 OpenAI `tools`、`tool_choice: auto/none`、非流式及 SSE 工具调用,以及由调用方执行工具后回传 `assistant.tool_calls` 与 `tool` 结果的完整多轮回路。BCY-LLM 只生成和校验工具调用,不会执行用户工具。调用 ID、工具名、JSON object 参数和结果对应关系会严格校验;未知、重复、缺失或错序结果返回 400。Chat Completions 的 `response_format` 与 Responses API 的 `text.format` 已支持 `json_object` 和标准 `json_schema`,对 GGUF 使用固定版 llama.cpp 的 grammar 约束解码,对第三方 OpenAI-compatible 服务转为等价的 Chat Completions 约束;Schema 名称、大小和复杂度会在推理前进行有界校验,非流式结果还会检查 JSON 语法。MLX 当前依赖尚无可验证的 JSON Schema grammar 引擎,因此 MLX 请求会明确返回 400,不会用提示词伪装结构化输出。Chat Completions 的 `logprobs: true` 与 `top_logprobs: 0...20` 已支持 GGUF 和第三方 OpenAI-compatible 模型,非流式与 SSE 都保留上游返回的真实 token、概率、bytes 和候选列表;上游缺失概率时请求失败。MLX tokenizer 尚不能可靠证明跨 token UTF-8 bytes 映射,因此 MLX 概率请求仍会在推理前明确返回 400,不会伪造 token 数据。其他会改变生成语义的未支持字段也会返回 400 和具体字段名。运行时或第三方服务没有返回 tokenizer 统计时 usage 保持 `null`,不会伪造数字。没有本地文本模型或第三方模型可用时,`/v1/models` 返回空列表,生成请求返回服务不可用。 `/v1/responses` 提供面向现代 OpenAI 客户端的真实生成路径,支持字符串 `input`、文本或 `input_image` 消息数组、`instructions`、`max_output_tokens`、采样参数与 `seed`、工具定义、`function_call`/`function_call_output` 完整回路、`text.format` 结构化输出、非流式 usage,以及带连续 `sequence_number` 的原生 Responses SSE 事件。流式请求以 `response.created` 开始,并根据停止原因以 `response.completed` 或 `response.incomplete` 结束,不复用 Chat Completions 的 `[DONE]`。当前不保存响应历史;`store: true`、`previous_response_id`、文件、自动截断等尚未实现的语义会明确返回 400,不会生成伪结果。为了兼容 Codex 等固定发送完整请求信封的客户端,`include`、`reasoning`、`prompt_cache_key` 和 `client_metadata` 会按字段逐个校验:`include` 只接受 `reasoning.encrypted_content`(响应里以 `reasoning.encrypted_content: null` 如实报告本地模型没有推理轨迹,不伪造加密内容),其他取值按 `include.<值>` 返回 400;`reasoning` 只在为空、`null` 或 `effort: "none"` 时接受,请求真实推理强度、摘要或上下文的 `reasoning.effort`、`reasoning.summary`、`reasoning.context` 会返回 400;`prompt_cache_key` 只作为最多 256 字节的不透明字符串校验并记录,本地按模型实例保存前缀缓存,不会把一个 key 伪装成缓存命中;`client_metadata` 只接受少量字符串键值,属于客户端遥测,不参与生成。 `/v1/realtime` 仅通过 WebSocket 提供原生双向音频。升级前执行与其它 API 相同的 Bearer 鉴权;客户端用 `session.update` 指定精确的模型 key、instance ID 和已验证音频格式,再以 `input_audio_buffer.append` 发送单帧 Base64 PCM16。服务端以 `response.audio.delta` 返回模型实际解码的音频帧;`response.cancel` 打断当前模型流,`session.cancel` 和 `session.close` 释放会话。当前不接受文本、Opus、任意采样率或任意帧长,不做 VAD、STT/TTS、录音、播放和历史保存。 `/v1/embeddings` 支持字符串或最多 128 条字符串数组输入,返回真实 MLX 或 GGUF embedding 向量、稳定输入顺序和 tokenizer 计算的 usage。本地 MLX 运行时使用模型自带 tokenizer、attention mask、pooling、LayerNorm 和 L2 归一化;GGUF 运行时使用受监督的 `llama-server --embedding` 进程;两者都不会从 LLM logits 或随机数伪造向量。单条输入最多 8192 token,总 UTF-8 输入不超过 1 MiB。`encoding_format` 支持默认的 `float` 数组和 OpenAI-compatible `base64`;后者是同一真实向量的 little-endian Float32 字节编码,不执行降维或数值改写。`dimensions`、token ID 数组等尚未真实实现的语义会返回 400。模型库会显示“文本生成”或“向量嵌入”用途,并由独立运行时加载。 MLX 推理会从 `config.json`、嵌套文本配置和有效的 `tokenizer_config.json` 自动识别上下文上限;当前自动加载上限为 256K Token。界面显示自动最大值,并允许在加载前手动选择更小的上下文。调用 `/api/v1/models/load` 时也可显式传入 `context_length`。 MLX 文本多轮请求会在上一轮完整成功结束后保留官方 `mlx-swift-lm` `ChatSession` 的真实 KV cache。只有请求历史精确延续上一轮“请求消息加完整 assistant 输出”前缀时才命中;图片、工具或工具历史、自定义 `stop`、分支会话、取消、生成失败、模型切换和卸载都会清除缓存。缓存只优化重复的 prompt 预填充,不改变模型输出语义;usage 仍按完整请求计算,因此不会把缓存命中误报成零 prompt token。`mlx-swift-lm` 当前没有向调用方公开精确的缓存 Token 偏移,因此 MLX 的 Chat Completions `prompt_tokens_details.cached_tokens` 与 Responses API `input_tokens_details.cached_tokens` 返回 `0`;GGUF 或第三方后端有可靠统计时才会报告实际值,不会用推算值伪造命中。 加载 MLX 模型前会根据权重大小、上下文窗口和当前设备物理内存执行保守预检;预检失败时不会先卸载当前模型,也不会进入不可恢复的加载状态。 “运行监控”页按开发者工作台展示本地服务器、已加载模型、实时语音模型健康状态与实时开发者日志;底部每秒采样 BCY-LLM 主进程及模型子进程的实际 RSS、CPU 和进程数。语音模型详情显示最近加载结果、进程健康检查、输入输出音频格式、并发上限、会话超时,以及输入转写、助手文字、助手文字增量和唤醒事件能力。开发者日志持续显示服务器启动/停止和请求、模型加载/卸载/推理、实时语音 worker 健康与会话事件,并可按服务器、模型、运行时和错误筛选。结构化开发者日志以 5 MiB 大小轮转保存在 `~/Library/Application Support/BCY-LLM/Logs/developer.ndjson`,运行指标仍保存在同目录的 `runtime.ndjson`;两类文件权限均为当前用户读写。日志不记录提示词、响应正文、转写正文、音频、图片内容、模型路径、访问令牌或请求头。 `/api/v1/models` 模型管理接口与 LM Studio 0.4 的 v1 路径和核心响应字段对齐。列表中的 `key` 是 BCY-LLM 模型库生成的稳定 UUID,不包含本地文件路径;MLX 或 GGUF 文本模型加载后,这个 UUID 也会作为 `/v1/models` 和推理请求的 `model` 标识,避免客户端在管理与推理接口之间转换路径。模型条目会通过 `type` 区分 `llm`、`vlm`、`embedding`、`reranker` 与 `realtime_voice`,`loaded_instances` 会报告当前加载实例;文本生成模型同时报告实际上下文。`models/load` 支持 `model`、文本模型可选的 `context_length`(256 至 262144)和 `echo_load_config`;省略 `context_length` 时使用模型声明上限与运行时上限中的较小值。MLX 上下文仍会受模型声明上限约束,GGUF 也会自动选择安全上下文,embedding 模型不接受不适用的 `context_length`。当前运行时不适用的 `eval_batch_size`、`flash_attention`、`num_experts` 和 `offload_kv_cache_to_gpu` 会明确返回 400,不会静默忽略。 为兼容 LM Studio 公开的 REST v0 客户端,`/api/v0` 提供同一套真实聊天、补全和 embedding 路由;`/api/v0/models` 返回 `object: "list"`、模型类型、MLX/GGUF 格式、架构、量化、加载状态和最大上下文。模型 ID 仍使用 BCY-LLM 生成的稳定 UUID,不暴露本地文件路径。v0 与 v1 共用相同的鉴权、请求校验和运行时,不会产生第二套不一致的推理逻辑。 `models/download` 会把请求解析为 Hugging Face 或 ModelScope 的精确仓库身份,读取服务端文件清单后进入与界面相同的持久化下载队列。支持 `namespace/model`、`https://huggingface.co/namespace/model`、`https://modelscope.cn/models/namespace/model`,以及显式的 `huggingface:`、`modelscope:` 前缀。未指定 `quantization` 时优先下载可完整验证的 MLX 快照;只有一个 GGUF 文件时可直接选择,存在多个 GGUF 变体时必须提供量化名称,服务不会猜测。返回的 `job_id` 可用于 `models/download/status/:job_id` 查询持久化进度、速度、预计完成时间和最终状态。文件仍会经过长度、哈希、目录边界及模型结构校验,成功后才原子安装并进入模型库。 “第三方 OpenAI-compatible 模型”支持保存多个服务配置,每个配置可以填写无需鉴权或使用 Bearer Token 的服务地址;常见的根地址和以 `/v1` 结尾的地址都可以使用。配置名称、地址和已发现模型会持久化,旧版单地址数据会自动迁移。Token 在读取 `/v1/models` 成功后才保存到 macOS Keychain,不写入偏好设置或模型数据库;移除配置时会清理对应凭据。连接成功后,模型会保存在“本地模型 > 第三方服务”中,并与当前加载的本地 MLX 或 GGUF 模型一起出现在 BCY-LLM 的 `/v1/models`;文本生成请求按 `model` 精确路由到本地 MLX、GGUF 或对应的第三方服务,embedding 请求路由到本地 embedding 运行时或对应的第三方服务。多个服务暴露同名模型时,BCY-LLM 会为冲突项生成带服务地址的稳定模型 ID,并在转发请求时恢复上游原始 ID,不会静默选择错误服务。第三方服务地址不能指向 BCY-LLM 自己的本地 API,避免形成递归请求。普通响应直接转发生成结果;`stream: true` 会向上游发起原生 SSE 请求并逐块传递内容,客户端断开时同步取消上游连接。跨来源重定向不会携带 Authorization、Cookie、Proxy-Authorization 或 X-API-Key;上游 SSE 响应同时受单事件 1 MiB、总正文 32 MiB 和有界缓冲限制。 先在“本地模型”中加载一个 MLX 或 GGUF 文本模型,再用模型列表返回的 `id` 发起请求: ```bash curl http://127.0.0.1:1234/v1/models curl http://127.0.0.1:1234/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"你好"}],"max_tokens":128}' curl -N http://127.0.0.1:1234/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"你好"}],"max_tokens":128,"stream":true,"stream_options":{"include_usage":true}}' curl http://127.0.0.1:1234/v1/responses \ -H 'Content-Type: application/json' \ -d '{"model":"YOUR_MODEL_ID","instructions":"请简洁回答","input":"你好","max_output_tokens":128}' curl http://127.0.0.1:1234/v1/embeddings \ -H 'Content-Type: application/json' \ -d '{"model":"YOUR_EMBEDDING_MODEL_ID","input":["第一段文本","第二段文本"],"encoding_format":"float"}' curl http://127.0.0.1:1234/api/v1/models curl http://127.0.0.1:1234/api/v1/models/load \ -H 'Content-Type: application/json' \ -d '{"model":"YOUR_MODEL_KEY","context_length":8192,"echo_load_config":true}' curl http://127.0.0.1:1234/api/v1/models/unload \ -H 'Content-Type: application/json' \ -d '{"instance_id":"YOUR_INSTANCE_ID"}' curl http://127.0.0.1:1234/api/v1/models/download \ -H 'Content-Type: application/json' \ -d '{"model":"mlx-community/YOUR_MLX_MODEL"}' curl http://127.0.0.1:1234/api/v1/models/download/status/YOUR_JOB_ID ``` 当前版本不提供聊天窗口、聊天会话列表或聊天历史持久化;界面只提供模型发现、下载、本地库、运行状态和设置。文本聊天接口仍作为 LM Studio/OpenAI 兼容推理协议提供,不代表应用内置聊天页面。 当前版本只呈现已经完整实现的模型库和语言设置,不在界面中展示未完成的功能入口。