Basalt API参考:OpenAI与Anthropic接口全兼容,3步接入本地LLM推理

原创2026-11-08 11:18:361,834 阅读

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 服务,负责对外暴露标准接口、管理模型加载/切换、并发槽位与诊断信息。

Basalt 网页界面在本地 LLM 推理流式输出回复

内置网页前端会实时显示流式回复、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 应用无缝切换到本地引擎,同时享受工具调用、结构化输出与流式思考等高级能力。

登录后查看全文
basalt