企业官网建设流程全解析

• 人工智能
• 大模型
• 推理引擎
• 本地部署
• 模型推理服务

本篇技术指南以仓库文档 docs/SERVER.md 为主体，系统讲解 ds4 项目的本地推理服务ds4-server：从最基本的启动参数、OpenAI/Anthropic 兼容 API 端点，到多会话批处理、图像输入、磁盘 KV 缓存与工具调用调试等生产级特性。读完本文，你将能够独立部署一个面向本机或可信内网的推理服务，并针对多用户、长上下文、Agent 工具调用等场景正确选择配置参数，同时理解每个参数背后的源码级实现依据。

快速开始：启动 ds4-server

构建完成后（构建方式见 README.md 中的平台指南表格：Apple Silicon 用make，DGX Spark 用make cuda-spark，Strix Halo / Framework Desktop 用make strix-halo，Ada/L40S 等 CUDA 卡用make cuda-generic），最简单的启动方式是：

./ds4-server --ctx 32768

这条命令以 32768 token 的上下文窗口启动服务，默认监听地址为http://127.0.0.1:8000（该默认值定义于 ds4_server.c，默认host = "127.0.0.1"、port = 8000）。核心启动参数说明如下：

几个关键安全点需要强调：

• 默认只监听127.0.0.1，不要轻易使用--host 0.0.0.0暴露到公网；
• --cors只添加跨域响应头，服务本身不做鉴权；
• 面向公网部署时，务必在服务前端自行叠加身份认证（authentication）与 TLS；
• 服务访问应限制在可信客户端范围内。

从 ds4_server.c 的参数解析代码可以看到，--host、--port、--chdir、--cors、--ctx、--trace、--batched-session、--kv-disk-*等选项都在启动入口被逐一解析并写入配置结构，最终统一传递到引擎与 HTTP 服务层。运行./ds4-server --help可查看全部选项及其默认值。

HTTP API 一览：五种协议兼容端点

ds4-server在同一端口上提供五类端点，覆盖主流 Agent 客户端与 OpenAI 生态工具：

这些路由在 ds4_server.c 中按method + path分发到对应处理逻辑。一个标准的 OpenAI 风格对话请求如下：

curl http://127.0.0.1:8000/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"Explain Redis streams."}],"stream":true}'

需要注意：端点接受的 Flash / PRO 模型名是兼容性别名（alias），并非实际加载的多个模型。启动时传入的 GGUF 文件才真正决定加载哪个模型——也就是说，服务内部只有一份已加载权重，model字段仅用于客户端协议兼容。例如deepseek-v4-flash、deepseek-v4-pro之类的名称只是让不同客户端可以按自己的习惯引用同一份模型。

协议能力方面：

• Chat、Responses、Anthropic 三类接口均支持工具调用（tools）与 SSE 流式输出；
• 推理内容（reasoning）与可见文本在各 API 的原生字段形式中分别返回；
• 支持标准采样参数与输出预算（output-budget）字段，且显式传入的请求参数优先于默认值。

默认采样与思考（Thinking）行为

服务的默认采样设置为：temperature 1、top-p 1、min-p 0.05。对于 DeepSeek 模型，思考默认开启。与思考相关的关键语义：

• reasoning_effort=max只有在上下文充足时才会选择 Think Max，否则回退到普通思考；
• xhigh映射到普通思考，不是Think Max；
• 需要直接回答时，使用think:false、一个被禁用的 thinking 对象，或选择一个非思考型模型别名。

多会话批处理：--batched-session 与解码执行模式

默认情况下，服务只有一个常驻会话（resident session）。当需要同时服务多个客户端会话时，使用：

./ds4-server --ctx 4096 --batched-session 4

--batched-session N的官方帮助说明是 "Keep N resident sessions and batch decode-ready requests"（见 ds4_help.c）。启用后，服务会预分配 N 个相互独立的 KV 状态，当所有 slot 都忙时，新请求进入队列等待。

两个实践要点：

1. 上下文与 slot 数量必须一起规划：能装下一次的上下文，未必能装下四次。例如--ctx 4096 --batched-session 4意味着 4 个会话共享 4096 的上下文预算，每个会话实际可用更少。
2. 空闲 slot 可在复用前缓存（cached），正在执行的请求不会被驱逐。

各后端/模型的解码执行方式

不同后端与模型组合下，多会话解码的执行路径并不相同：

理解两种模式的区别很重要：有序回退（ordered fallback）是逐行串行执行各会话请求，它提供的是并发与调度公平性（concurrency and scheduling fairness），而不是原生批处理带来的聚合加速（aggregate speedup）。此外，原生分组可能轻微改变浮点归约顺序（floating-point reduction order），在严格数值比对场景下需要注意；包含图像的 V4.1 会话一律使用有序回退。

长 prefill 与混合调度

长 prefill（长提示的首轮处理）会在有活跃解码器（active decoders）时，以有界区间让路（yield），通常为 128 token。该区间可通过--mixed-prefill-quantum N调整（用于测试；ds4_help.c 注明默认 128，GLM-5.3 最小 1024）。

会话批处理服务使用普通目标解码（target decoding），不使用 MTP/DSpark 投机解码路径。对于八卡 L40S 的多用户部署示例，参见 docs/CUDA_MULTI_GPU.md 的 "Serve multiple users" 一节。

图像输入：视觉模型的请求格式与限制

为 Flash/PRO 视觉模型启用图像输入，需要加载配套的语言 GGUF 与视觉编码器：

./ds4-server -m flash.gguf --vision vision.gguf

具体模型对应的视觉文件选择，参见 docs/MODELS.md 的 vision 一节。不同协议下的图像格式约定：

• OpenAI chat 与 Responses：接受内联 PNG/JPEG 的data URI；
• Anthropic：接受base64 图像源；
• 远程 URL 与服务端本地文件路径一律拒绝；
• 请求中的图像块保持其在请求中的原始顺序。

服务端对图像请求有硬性上限（ds4_server.c 会返回 "too many images; at most 16 are allowed"）：最多 16 张图片，HTTP body 上限 64 MiB（max_body = 64 * 1024 * 1024，见 ds4_server.c）。

磁盘 KV 缓存：跨会话与跨重启复用前缀

磁盘缓存（disk KV cache）的价值在于：把可复用的前缀（prefix）保存下来，跨 slot 复用和服务器重启都能受益，避免每次重复做完整 prefill。

./ds4-server --ctx 100000 \ --kv-disk-dir /tmp/ds4-kv --kv-disk-space-mb 8192

客户端可以重新发送完整对话历史。服务端会依次尝试：先查活 token 前缀（live token prefix），再查磁盘上兼容的渲染文本前缀（compatible rendered-text prefixes），最后对新后缀做 prefill。在多 slot 场景下，每个 slot 各有自己的活状态，磁盘是额外的持久化层，而不是唯一保留会话的方式。

几个加载与分布细节：

• TP（张量并行）缓存加载会在两个 rank 上重建已保存的 token 前缀，并非两个 GPU 状态的瞬时恢复；
• 流水线（pipeline）加载会把保存的层状态按其路由重新分布。

缓存边界控制参数

默认参数旨在避免保存脆弱的 token 边界（fragile token boundaries）。对不寻常的工作负载，可用以下参数精确控制（默认值见 ds4_help.c，也可用./ds4-server --help查询）：

--kv-disk-space-mb N的默认磁盘预算为 4096（启用时）。量化变体之间可能共享兼容前缀；如果只想复用量化完全相同的缓存，追加--kv-cache-reject-different-quant，它会拒绝由不同路由专家量化（routed-expert quantization）写入的检查点。

隐私与清理注意事项

缓存文件中包含提示文本与模型状态，必须把缓存目录视为私有数据目录。该目录是可丢弃的（disposable）；清理前请先停止服务器。

工具历史与调试：DSML 工具回放与 Trace

针对 DeepSeek 模型，服务器会保留采样的 DSML 工具块（tool blocks），并为工具调用分配不可猜测的 ID。回放这些 ID 可以避免对格式不同但内容相同的 JSON 历史做重复 tokenize。这个有界的回放映射表可以随缓存文件一并存储；当精确回放不可用时，规范化渲染（canonical rendering）可能需要重建前缀的一部分。

相关参数：

• --tool-memory-max-ids N：限制保存在 RAM 中的精确工具调用 ID 数量，默认 100000（ds4_help.c）；
• --disable-exact-dsml-tool-replay：关闭精确的采样 DSML 工具回放映射，用于诊断性对比（ds4_help.c）。

调试利器是 Trace 输出：

./ds4-server --trace /tmp/ds4-trace.txt

Trace 会记录：提示渲染（prompt rendering）、缓存决策（cache decisions）、生成文本、工具解析器事件（tool-parser events）。Trace 文件可能包含敏感内容，注意保护。

缓存格式的实现位置

磁盘缓存格式属于实现细节。当前头部与扩展名定义在 ds4_kvstore.h 与 ds4_kvstore.c 中（例如 ds4_kvstore.h 说明了检查点如何表示"位于提示前部的字节"，以及头部字节 7 用于 Flash 的向后兼容标记）；模型相关的负载处理在 ds4.c 中。

接入 Coding Agent 客户端

ds4-server的一个主要使用场景是为本地 Coding Agent 提供推理后端。推荐这样启动：

./ds4-server --ctx 100000 --kv-disk-dir /tmp/ds4-kv --kv-disk-space-mb 8192

然后按 docs/CLIENTS.md 的说明配置客户端（Pi、OpenCode、Codex CLI、Claude Code 都有现成配置示例）。配置要点包括：客户端上下文上限不要超过服务器分配；输出 token 同样消耗上下文，客户端限额不会扩大服务器分配；dsv4-local这类字符串只是占位符而非服务端认证凭据。Agent 客户端可能发送很大的初始提示，首次 prefill 可能较慢，磁盘缓存有助于后续会话复用兼容前缀。

相关文档导航

本文是服务器使用主题的入口，深入特定平台与模型细节可继续阅读：

• docs/CLIENTS.md：Pi / OpenCode / Codex CLI / Claude Code 客户端配置
• docs/CUDA_MULTI_GPU.md：CUDA 多卡与张量并行部署
• docs/MODELS.md：各模型下载、量化与视觉（vision）支持
• docs/DISTRIBUTED.md：分布式与多机部署
• docs/TESTING.md：回归测试与调试工具

结合本文的启动参数、API 端点表与各控制参数的默认值（全部可在./ds4-server --help中复核），你就可以针对单用户桌面、多会话 Agent 工作台或可信内网服务等不同场景，配置出一套贴合需求的 ds4 本地推理服务。

• 人工智能
• 大模型
• 推理引擎
• 本地部署
• 模型推理服务