Basalt API参考:OpenAI与Anthropic接口全兼容,3步接入本地LLM推理
Basalt API参考:OpenAI与Anthropic接口全兼容,3步接入本地LLM推理
Basalt 是一款运行在 NVIDIA Blackwell 显卡上的本地 LLM 推理引擎,支持 Qwen3.8-Flash-Next 与 DeepSeek-V4.1-Flash 混合专家模型,并以服务(serve)方式同时兼容 OpenAI 与 Anthropic 两套 API。你只需把现有应用的 base_url 指向本地地址,就能让任何 AI 应用零改动接入本地推理,全程无需外部云服务。
什么是 Basalt:面向本地 LLM 的推理引擎
Basalt 把 MoE(混合专家)模型中放不进显存的专家放到内存(甚至第二块显卡)里,用 CUDA 13 高效计算。它的服务端是一个独立的 Python 服务,负责对外暴露标准接口、管理模型加载/切换、并发槽位与诊断信息。
内置网页前端会实时显示流式回复、GPU 负载与速率,方便你一边调试一边观察。下面进入 API 参考。
一键启动 Basalt API 服务器
Basalt 用一个 JSON 配置文件驱动,核心就三部分:models(模型列表)、engine(引擎参数)、server(服务参数)。
{
"version": 2,
"models": [{ "model": "models/Qwen3.8-FN-NVFP4-DQ6_K.basalt", "gpu": "0,1", "kv": "int8" }],
"engine": { "resident-experts": true },
"server": { "port": 8080 }
}
用如下命令启动,服务默认监听 127.0.0.1:8080:
bin/basalt serve --config basalt_config.json
需要对外提供或加访问控制时,通过命令行指定密钥(api-key 只能写在命令行,不能进配置文件):
bin/basalt serve --config basalt_config.json --api-key sk-你的密钥 --host 0.0.0.0
所有可调参数见 配置文件参考,运行与并发行为见 running.md。
兼容的 API 接口清单 🗂️
Basalt 的路由实现集中在 handler.py,同时挂载了 OpenAI 与 Anthropic 两套主流接口,外加若干运维接口:
| 类别 | 方法与路径 | 作用 |
|---|---|---|
| OpenAI | POST /v1/chat/completions |
对话补全,支持流式 / 工具 / 结构化输出 |
| OpenAI | POST /v1/responses |
Responses API(无状态) |
| Anthropic | POST /v1/messages |
消息接口,支持 thinking 与 tool_use |
| Anthropic | POST /v1/messages/count_tokens |
估算 token 数 |
| 模型管理 | GET /v1/models、GET /v1/status |
列出模型与状态 |
| 运维 | GET /health、GET /metrics、GET /slots、GET /api/logs |
健康检查、指标、槽位、日志 |
| 资源 | POST /v1/vram、POST /v1/load、POST /v1/unload |
调整显存预留、手动加载/卸载 |
请求体里的 model 字段填 /v1/models 返回的名字即可,多个模型由路由按名字分发并自动切换。
OpenAI Chat Completions 接口:最通用的接入方式
这是兼容性最广的入口,客户端可直接使用 OpenAI SDK 或任意 HTTP 库。流式输出采用标准 SSE,末尾以 data: [DONE] 结束,并附带 usage(含命中缓存的 prompt_tokens_details.cached_tokens)与工具调用 tool_calls。
curl http://127.0.0.1:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"Qwen3.8-Flash-Next","stream":true,
"messages":[{"role":"user","content":"你好,介绍一下你自己"}]}'
关键能力(实现见 openai.py):
- 流式与非流式:
stream为true时逐块返回,false时聚合成完整chat.completion。 - 思考内容:推理模型把思考过程放进
reasoning_content,正文放进content。 - 工具调用:支持
tools、tool_choice,流式下工具参数分片合并。 - 结构化输出:
response_format支持json_object与json_schema,由引擎用语法约束(grammar)保证合法 JSON。 - logit_bias:传
{token_id: 偏置}映射,取值 -100~100(-100 即禁用该 token),详见 logit_bias.py。
Anthropic Messages 接口:原生 thinking 与工具
如果你用的是 Anthropic 客户端,POST /v1/messages 完全对齐官方事件协议:message_start → content_block_* → message_delta → message_stop,思考内容以 thinking 块流式返回,工具以 tool_use 块返回(实现见 anthropic.py)。
curl http://127.0.0.1:8080/v1/messages \
-H "x-api-key: 你的密钥" -H "anthropic-version: 2023-06-01" \
-d '{"model":"Qwen3.8-Flash-Next","max_tokens":2048,
"messages":[{"role":"user","content":"用一句话解释量子计算"}]}'
system字段承载系统提示,max_tokens必填。- 支持
thinking(思考预算)与tool_use流式分片。 - 结构化输出通过
output_config.format(旧名output_format)传入json_schema,映射逻辑见 structured.py。
OpenAI Responses 接口:无状态的现代化入口
POST /v1/responses 提供 OpenAI Responses API 语义(实现见 responses.py)。它是无状态的:客户端需在 input 里回传整段对话(store:false),思考内容以 reasoning_text 返回,也支持 encrypted_content 往返。适合已经在向 Responses API 迁移的应用。
快速接入示例:改一行 base_url
大多数客户端只需改基础地址与密钥:
import openai
client = openai.OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="sk-你的密钥")
resp = client.chat.completions.create(
model="Qwen3.8-Flash-Next",
messages=[{"role": "user", "content": "用 Python 写一个快速排序"}],
)
print(resp.choices[0].message.content)
💡
model名称以GET /v1/models返回为准;开启--api-key后所有/v1/*接口都会校验Authorization: Bearer或x-api-key。
运维与可观测接口:把本地推理管好
这些接口让本地服务像云 API 一样可控:
GET /health:返回loaded、loading、percent、max_context等,判断是否就绪。GET /metrics:引擎事实、实时槽位、最近请求、GPU 硬件与速率历史,是内置统计页的数据源。GET /v1/models:列出所有配置模型及其加载/失败状态。POST /v1/load/POST /v1/unload:在请求间隙手动加载或卸载模型。
采样参数(temperature、top-p、top-k、seed 等)的完整取值与默认值见 sampling.md;多模型与路由行为见 models.md。
小结
Basalt 让「本地 LLM 推理」拥有与云端一致的接口体验:OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 三套主流 API 全部兼容,并附带完整的健康检查、指标与资源管理接口。只需一个 JSON 配置加一条启动命令,你就能把现有 AI 应用无缝切换到本地引擎,同时享受工具调用、结构化输出与流式思考等高级能力。
