# llm_serve **Repository Path**: awol2010ex/llm_serve ## Basic Information - **Project Name**: llm_serve - **Description**: 将任意 OpenAI 兼容接口的大模型绑定 **MCP**、**Skills** 后,发布为一个新的 OpenAI 兼容 API 服务。 - **Primary Language**: Unknown - **License**: AGPL-3.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-02 - **Last Updated**: 2026-07-15 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # llm_serve 将任意 OpenAI 兼容接口的大模型绑定 **MCP**、**Skills** 后,发布为一个新的 OpenAI 兼容 API 服务。 ## 核心能力 | 能力 | 说明 | |------|------| | **OpenAI 兼容** | 提供标准 `/v1/chat/completions`、`/v1/models` 端点 | | **Skills** | Claude SKILL.md 兼容格式,自动注册为 OpenAI function calling tool | | **MCP** | 支持 `mcp_servers.json`(Claude/Trae 标准格式)或编程式注入 | | **SSE 流式** | 支持非流式与 SSE 流式响应 | | **多模态(图片)** | `content` 数组支持 `image_url` 片段,透传给上游视觉模型(Qwen-VL / gpt-4o 等) | | **流式可观测性** | 流式中透出模型思考过程、工具调用输入与返回结果,兼容任意 OpenAI 兼容客户端 | | **代理模式** | 作为上游模型的智能代理,自动调用 tool/skill/mcp | ## 架构 ``` ┌──────────────┐ ┌────────────────┐ ┌─────────────────┐ │ Chatbox / │────►│ llm_serve │────►│ OpenAI 兼容 API │ │ AI SDK │ │ (axum HTTP) │ │ (ModelScope等) │ └──────────────┘ └───────┬────────┘ └─────────────────┘ │ ┌────────┴────────┐ │ ServeEngine │ ├─────────────────┤ │ Skills │ MCP │ │ Manager │Manager│ └─────────┴───────┘ ``` ## 快速开始 ### 环境变量 ```bash export OPENAI_API_KEY="sk-xxx" export OPENAI_BASE_URL="https://api.openai.com/v1" # 或 ModelScope 等 export OPENAI_MODEL="gpt-4o" ``` 可选: ```bash export SKILLS_DIR="./skills" # Skills 目录 export MCP_CONFIG_PATH="./mcp_servers.json" # MCP 配置 export LLM_SERVE_HOST="0.0.0.0" # 监听地址 export LLM_SERVE_PORT="8080" # 监听端口 export LLM_SYSTEM_PROMPT="你是一个有用的助手" # 系统提示,作为 agent preamble 注入(可设定人格/行为规范) export LLM_SERVE_MAX_TURNS="-1" # tool-calling 轮次上限;-1 或不设 = 不限制(默认) export LLM_SERVE_WATCH_SKILLS="true" # 实时监控 skills 目录并热重载(默认关闭,需配合 SKILLS_DIR) ``` ### 启动服务 ```bash cargo run --release --example simple_server ``` ### 测试端点 ```bash # 健康检查 curl http://localhost:8080/health # 列出模型 curl http://localhost:8080/v1/models # 非流式聊天 curl http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4o","messages":[{"role":"user","content":"你好"}],"stream":false}' # 流式聊天 (SSE) curl http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4o","messages":[{"role":"user","content":"你好"}],"stream":true}' ``` > 注:聊天端点需要有效的 `OPENAI_API_KEY` 才能调用。下面的工具测试端点**无需 API key**,可独立验证工具注册与执行。 #### 无需 API key 的工具测试端点 `simple_server` 内置了一个 rig 原生 `Tool` 示例(`CalculatorTool`,通过 `register_tool` 注册),并提供以下端点用于离线测试: ```bash # 列出所有已注册工具(Skills + MCP + 自定义 rig Tool) curl http://localhost:8080/v1/tools # 直接调用 calculator 工具(绕过 LLM) curl -X POST http://localhost:8080/v1/tools/calculator/call \ -H "Content-Type: application/json" \ -d '{"operation":"add","a":3,"b":4}' # => {"success":true,"tool":"calculator","output":"7"} # 测试错误分支(除零) curl -X POST http://localhost:8080/v1/tools/calculator/call \ -H "Content-Type: application/json" \ -d '{"operation":"divide","a":1,"b":0}' # => {"error":{"message":"调用 tool 'calculator' 失败: ...","type":"tool_call_error","code":"tool_call_error"}} ``` `/v1/tools/{name}/call` 对任意已注册工具都生效(包括 MCP 工具),`args` 即工具参数的 JSON 字符串,是单独验证工具逻辑的轻量入口。 ## 流式可观测性(思考过程 / 工具调用) 为了让 Chatbox 等**仅渲染 `delta.content`** 的 OpenAI 兼容客户端也能观察 agent 的中间过程,`chat_stream()` 会把以下事件作为**普通文本 delta** 透出到流中(而非自定义 SSE 事件类型): | 事件 | 流中呈现形式 | rig-core 来源 | |------|--------------|---------------| | 模型思考过程 | `💭 **思考过程**` + 文本 + 分割线 | `Reasoning` / `ReasoningDelta` | | 工具调用输入 | `🔧 **调用工具** \`名称\`` + JSON 参数 | `ToolCall` | | 工具返回结果 | `📤 **工具返回** \`名称\`` + 结果文本 | `StreamUserItem::ToolResult` | 这些文本以 markdown 形式嵌入回复正文,因此**流式与非流式响应都会包含**(非流式由 `chat_with_temperature` 内部收集流式输出拼接而成)。 实现要点: - 工具调用与返回通过 rig-core 的 `internal_call_id` 关联,确保结果对应到正确的工具名(rig-core 不会在 result 中回显 call_id) - `ToolCallDelta` 增量事件被刻意忽略,避免与完整 `ToolCall` 重复输出 - `Reasoning`(完整块)与 `ReasoningDelta`(增量)二者只会来其一,用 `in_reasoning` 状态机避免重复输出「思考过程」标题 > 若你不希望中间过程污染最终文本(例如仅用于调试),可在 `src/engine.rs` 的 `chat_stream` 中关闭对应的 `emitter.emit(...)` 调用。 ## 多模态(图片输入) 当上游模型是视觉模型(如 Qwen-VL、gpt-4o、GLM-4V 等)时,可在 `content` 数组中混入 `image_url` 片段,图片会被一并发送给模型。格式完全兼容 OpenAI Vision API: ```bash # 远程图片 URL curl http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-vl-max", "messages": [{ "role": "user", "content": [ {"type": "text", "text": "这张图片里有什么?"}, {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg", "detail": "high"}} ] }], "stream": true }' ``` 也支持 base64 `data:` URI(无需额外声明 media_type,直接放进 `url`): ```json { "type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."} } ``` 要点: - `detail` 可选,取值 `low` / `high` / `auto`(默认 `auto`),映射 OpenAI 的图片精度参数 - 一条消息里可放多张图片,也可与多段文本混排;所有 `image_url` 片段会被收集后附加到 prompt - 无图片时行为与纯文本完全一致(自动退化),向后兼容 - 图片是否被真正理解取决于**上游模型是否为视觉模型**——本服务只负责透传,不做图片下载/转码 ## 库用法 ```rust use llm_serve::{ServeConfig, ServeEngine, ChatMessage, MessageContent}; // 推荐用 from_env() 读取全部环境变量构造配置(含 watch_skills 等开关) let config = ServeConfig::from_env(); // 也可编程式构造,但需补齐所有字段(如 max_repeated_tool_calls、watch_skills)。 // 例如开启 skills 目录实时监控: // let config = ServeConfig { watch_skills: Some(true), ..ServeConfig::from_env() }; let engine = ServeEngine::new(config).await?; // 非流式 let text = engine.chat(&messages).await?; // 流式 let mut rx = engine.chat_stream(&messages, 0.7).await?; while let Some(chunk) = rx.recv().await { println!("{}", chunk); } ``` ## Skills 实时监控与动态加载 > 默认**关闭**。开启后,服务运行期间对 `skills/` 目录的增删改会被**自动热重载**,无需重启进程。 开启方式(二选一): ```bash # 环境变量(推荐) export LLM_SERVE_WATCH_SKILLS=true export SKILLS_DIR="./skills" ``` 或编程式: ```rust let config = ServeConfig { watch_skills: Some(true), skills_dir: Some("skills".into()), ..ServeConfig::from_env() // 其余字段由环境变量填充 }; ``` 行为: - **新增**一个 `skills//SKILL.md` → 即时注册为新工具,LLM 下一轮即可调用 - **修改**已有 SKILL.md(名称/描述/参数/指引) → 自动覆盖更新(rig-core `add_tool` 同名 last-wins) - **删除**整个 skill 目录 → 自动从工具集中移除 - 监视是**递归**的(`notify::recommended_watcher`,Windows 走 `ReadDirectoryChangesW`),子目录变更同样生效 - 内置 **500ms 去抖**:编辑器保存触发的一连串事件会合并为一次重载,避免抖动 - 重载失败只记日志、不影响服务继续运行;重载逻辑集中在 `engine::ServeEngine::reload_skills` / `apply_skills` 边界: - 只有**开启开关且配置了 `skills_dir`** 才会启动监控;否则行为与旧版本完全一致(启动期一次性加载) - 热重载仅覆盖由 skills 目录加载的技能;通过 `register_tool` 注入的自定义 rig Tool 仍由调用方自行管理 - 监控基于 OS 文件事件,依赖文件系统支持(本地目录、常见挂载点均可;某些网络文件系统事件可能不可靠) ## Skills Skills 遵循 Claude SKILL.md 格式,放在 `skills//SKILL.md` 下。 ### 示例: `skills/echo/SKILL.md` ```yaml --- name: echo description: 回显用户输入的文字,可指定重复次数 parameters: message: type: string description: 要回显的消息 required: true times: type: integer description: 重复次数 required: false default: 1 --- # Echo Skill 你是一个回显工具。收到参数后,将 message 重复 times 次输出。 ``` ### Skills 工作原理 1. 启动时扫描 `SKILLS_DIR` 下的所有 `SKILL.md` 文件 2. 解析 YAML frontmatter 获取 name、description、parameters 3. 将每个 skill 注册为 rig-core Tool(自动生成 OpenAI function calling schema) 4. 当 LLM 调用该 tool 时,发起一次子 LLM 调用:system prompt = skill body,user message = tool 参数 ## 注册自定义 rig Tool(原生写法) 除了 Skills 和 MCP,你也可以直接用 rig-core 的 `Tool` trait 写工具,运行时挂到引擎上。底层走 `ToolServerHandle::add_tool`,任意 `impl Tool` 都能注入,且对后续请求立即生效。 ```rust use rig_core::completion::ToolDefinition; use rig_core::tool::Tool; use serde::{Deserialize, Serialize}; #[derive(Deserialize)] struct AddArgs { a: i32, b: i32, } #[derive(thiserror::Error, Debug)] enum CalcError { #[error("compute failed")] Failed, } struct CalculatorTool; impl Tool for CalculatorTool { const NAME: &'static str = "calculator"; type Error = CalcError; type Args = AddArgs; type Output = i32; async fn definition(&self, _prompt: String) -> ToolDefinition { ToolDefinition { name: "calculator".into(), description: "将两个整数相加".into(), parameters: serde_json::json!({ "type": "object", "properties": { "a": { "type": "integer" }, "b": { "type": "integer" } }, "required": ["a", "b"] }), } } async fn call(&self, args: Self::Args) -> Result { Ok(args.a + args.b) } } // 引擎启动后注册 engine.register_tool(CalculatorTool).await?; ``` > 重复同名 tool 会覆盖(last-wins);Skills、MCP、自定义 Tool 三者在同一个 toolset 内共存,LLM 可自由调用任意一种。 ## MCP ### 配置文件格式 `mcp_servers.json` 支持两种传输方式: #### Stdio 传输(默认) 通过子进程启动 MCP 服务器,使用 `command` + `args` + `env` 配置: ```json { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/temp"], "env": {} }, "desktop-commander": { "command": "npx", "args": ["-y", "@wonderwhy-er/desktop-commander@latest"] } } } ``` 多个 MCP 服务器可共存:所有服务器的工具会被**聚合进同一个 toolset**,LLM 可以统一调用任意一个服务器暴露的工具。上面的 `desktop-commander` 即「桌面服务器」配置,可提供读写文件、执行命令等桌面操作能力。 #### Streamable HTTP 传输 通过 HTTP SSE 连接远程 MCP 服务器,使用 `url` + `headers` 配置: ```json { "mcpServers": { "my-remote-mcp": { "url": "http://localhost:3000/mcp", "headers": { "Authorization": "Bearer ${MCP_AUTH_TOKEN}" } } } } ``` 判别逻辑:配置中有 `url` 字段则视为 Streamable HTTP,否则视为 Stdio(向后兼容)。 #### 环境变量展开 `command`、`args`、`env`、`url` 以及 `headers` 的值都支持环境变量展开,便于把密钥 / 路径从配置中剥离: - `${VAR}` —— 取环境变量 `VAR`;若未设置则**启动报错**(显式暴露配置问题,避免把空串当密钥用)。 - `${VAR:-默认值}` —— 若 `VAR` 未设置则使用 `默认值`(按字面量,不递归展开)。 ```json { "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}", "API_BASE": "${GH_API:-https://api.github.com}" } } } } ``` > 仅识别 `${...}` 形式,不支持裸 `$VAR`,以避免与 Windows 路径(如 `C:\tmp`)冲突;未闭合的 `${` 按字面量保留。 ### 编程式注入(Stdio) ```rust let mcp_config = llm_serve::McpConfig { servers: vec![ llm_serve::McpServerConfig { name: "filesystem".into(), transport: llm_serve::McpServerTransport::Stdio { command: "npx".into(), args: vec!["-y", "@anthropic/mcp-server-filesystem", "/tmp"] .into_iter().map(String::from).collect(), env: std::collections::HashMap::new(), }, }, ], }; ``` ### 编程式注入(Streamable HTTP) ```rust let mcp_config = llm_serve::McpConfig { servers: vec![ llm_serve::McpServerConfig { name: "remote-mcp".into(), transport: llm_serve::McpServerTransport::StreamableHttp { url: "http://localhost:3000/mcp".into(), headers: std::collections::HashMap::new(), }, }, ], }; ``` ### 平台兼容性 - **Windows**: 自动为 `npx` 等无扩展名命令追加 `.cmd`,自动映射 `/tmp` → `C:/temp` - **Linux/macOS**: 直接使用原生命令 ## API 端点 | 方法 | 路径 | 说明 | |------|------|------| | `GET` | `/health` | 健康检查 | | `GET` | `/v1/models` | 列出可用模型 | | `POST` | `/v1/chat/completions` | 聊天补全(支持 stream) | | `GET` | `/v1/tools` | 列出所有已注册工具(Skills + MCP + 自定义 rig Tool) | | `POST` | `/v1/tools/{name}/call` | 直接调用指定工具(绕过 LLM,无需 API key) | ### 请求/响应格式 完全兼容 OpenAI Chat Completions API。`content` 字段同时支持字符串和数组格式: ```json // 字符串格式 {"role": "user", "content": "你好"} // 数组格式(Chatbox 等现代客户端) {"role": "user", "content": [{"type": "text", "text": "你好"}]} // 数组格式 + 图片(多模态,需上游为视觉模型) {"role": "user", "content": [ {"type": "text", "text": "描述这张图"}, {"type": "image_url", "image_url": {"url": "https://.../a.jpg", "detail": "auto"}} ]} ``` ## 项目结构 ``` src/ ├── lib.rs # 库入口,统一导出 ├── config.rs # 配置管理 (env / JSON 文件) ├── engine.rs # 核心引擎 (chat / chat_stream / agent) ├── mcp.rs # MCP 连接管理 └── skills/ ├── mod.rs # Skills 模块入口 ├── loader.rs # SKILL.md 解析器 └── tool.rs # Skill → rig-core Tool 适配器 examples/ └── simple_server.rs # 完整 HTTP 服务示例 ``` ## 依赖 | 库 | 版本 | 用途 | |----|------|------| | [rig-core](https://crates.io/crates/rig-core) | 0.39 | LLM 编排(agent/tool/streaming) | | [rmcp](https://crates.io/crates/rmcp) | 1.8 | MCP 客户端(stdio + Streamable HTTP transport) | | [axum](https://crates.io/crates/axum) | 0.8 | HTTP 服务框架 | | [tokio](https://crates.io/crates/tokio) | 1 | 异步运行时 | ## 已知限制 - `chat_stream()` 通过 `messages_to_prompt_message()` 构造 prompt:**文本**部分仍按 `messages_to_prompt()` 扁平化为单条字符串(丢失多轮对话的 role 结构),**图片**(`image_url`)部分则以 `UserContent::Image` 片段完整保留并附加到该 prompt - `chat_with_temperature()` 通过内部收集 streaming 输出来兼容第三方 API,token 用量统计为 0 - 思考过程 / 工具输入 / 输出以文本形式注入回复正文,**流式与非流式响应都会包含**;如需对最终文本「纯净」处理,需在 `engine.rs` 关闭对应 emit - 单模型架构,不支持多模型路由 ## License Apache-2.0