本地 HTTP 引擎集成指南

声墨 离线客户端内置了一个本地 HTTP 服务，除了通过桌面界面使用外，你还可以让任意程序或 AI 智能体通过 HTTP API 直接调用语音转写能力。

使用方式

绝大多数用户无需任何操作，9532 是默认值，开箱即用。

如有端口冲突，在系统环境变量中设置：

VOICEINK_ASR_PORT=19532

重启应用后生效。不需要 .env 文件，直接设置系统 / 用户级环境变量即可（Windows 可在“系统属性 → 高级 → 环境变量”里添加）。

注意：VOICEINK_ASR_PORT 是 Rust 后端在进程启动时读取的环境变量，不是 Vite / 前端 VITE_ 变量；.env 文件中的设置对打包后的 Tauri 应用不生效。只有操作系统环境变量才有效。

文档说明：本文中的 http://127.0.0.1:9532 适用于默认配置的绝大多数用户；如果你修改过端口，请将示例里的 9532 替换为你的实际端口。

集成前必读

本引擎只负责处理音频数据，不负责录音。

调用方（你的程序或智能体）需要自行完成：

• 麦克风权限申请
• 音频录制（开始 / 停止）
• 将录好的音频文件或 Base64 数据发送给本引擎

引擎接收音频后负责：识别 → 返回文字，仅此而已。

核心概念

组件	职责
本地 HTTP 服务	模型管理、接收音频、执行识别、返回文本、标点后处理
你的程序 / 智能体	录音、麦克风采集、发送音频、处理结果、展示或粘贴

关键边界：HTTP 服务负责"识别引擎"，录音控制由调用方自行负责。

启动本地 HTTP 服务

方式 A：随桌面客户端自动启动

正常启动声墨 桌面客户端后，本地 HTTP 服务会自动运行；绝大多数用户的默认地址是：

http://127.0.0.1:9532

方式 B：无界面独立启动（headless）

不需要打开桌面界面，直接启动后台服务：

python src-tauri\python\asr_server.py --host 127.0.0.1 --port 9532

完整参数示例：

python src-tauri\python\asr_server.py `
  --host 127.0.0.1 `
  --port 9532 `
  --models-dir D:\VoiceInkModels `
  --log-file D:\VoiceInkLogs\asr.log

参数	说明	默认值
--host	监听地址	127.0.0.1
--port	监听端口	9532
--models-dir	模型存放目录	应用默认路径
--log-file	日志文件路径	无（输出到控制台）

当前版本仅支持本地调用

当前版本的 HTTP 服务仅支持本地调用（127.0.0.1），不开放局域网访问。这是出于安全考虑：没有认证机制的服务一旦暴露到局域网，任何同网设备都可无需密码直接调用。

如需局域网 / 内网部署，请联系定制服务。

第一步：加载模型

独立启动服务后不会自动加载模型，需手动调用一次：

POST http://127.0.0.1:9532/models/load
Content-Type: application/json

不传 model_id（推荐），后端自动选择已安装模型：

{
  "device": "cpu"
}

指定模型：

{
  "model_id": "paraformer-zh-large",
  "device": "cpu"
}

按优先级选择：

{
  "preferred_model_ids": ["sensevoice-small", "paraformer-zh-large"],
  "device": "cpu"
}

确认模型已就绪

POST /models/load 是异步的，需轮询确认：

GET http://127.0.0.1:9532/models/current

当返回中出现以下字段时，说明加载完成：

{
  "modelStatus": "loaded",
  "loaded": true,
  "modelId": "paraformer-zh-large"
}

第二步：提交音频转写

方案 A：文件路径接入

适合本地自动化脚本、智能体工作流等场景。

POST http://127.0.0.1:9532/tasks/transcribe
Content-Type: application/json

{
  "file_path": "D:/records/demo.wav",
  "input_type": "audio",
  "language": "auto"
}

获取 task_id 后轮询结果：

GET http://127.0.0.1:9532/tasks/{task_id}

方案 B：Base64 内存音频

适合不想落地文件的轻量程序、浏览器插件等。

POST http://127.0.0.1:9532/tasks/transcribe
Content-Type: application/json

{
  "audio_base64": "<BASE64_ENCODED_AUDIO>",
  "input_type": "audio",
  "format": "wav",
  "sample_rate": 16000,
  "language": "auto"
}

支持的音频格式（format 字段）：

格式标识	说明
pcm_s16le	原始 PCM 16-bit 小端（默认）
wav	WAV 容器
audio_ogg_opus	OGG(Opus) 压缩
audio_webm_opus	WebM(Opus) 压缩
mp3	MP3
m4a / aac	AAC
flac	FLAC 无损

压缩格式通过 FFmpeg 自动解码，调用方无需手动转码。

同步转写（短音频）

POST http://127.0.0.1:9532/transcribe
Content-Type: application/json

{
  "audio_base64": "<BASE64>",
  "format": "wav",
  "language": "auto"
}

直接返回转写文本，无需轮询，适合短片段。

第三步：标点恢复（可选）

POST http://127.0.0.1:9532/postprocess/punctuation
Content-Type: application/json

{
  "text": "今天开会讨论了三个议题第一个是预算审批"
}

完整最小工作流

1. GET  /health                    → 确认服务在线
2. POST /models/load               → 触发模型加载
3. GET  /models/current            → 轮询直到 modelStatus = loaded
4. [你的程序] 采集或准备音频文件
5. POST /tasks/transcribe          → 提交音频，获取 task_id
6. GET  /tasks/{task_id}           → 轮询拿到转写文本
7. POST /postprocess/punctuation   → （可选）标点恢复

AI 智能体集成示例

在 Dify、Coze、n8n 等平台中，将声墨 配置为 HTTP 工具节点：

• 工具地址：http://127.0.0.1:9532/tasks/transcribe
• 方法：POST
• 请求体：传入音频文件路径或 Base64 编码
• 结果提取：轮询 /tasks/{task_id} 中的 text 字段

智能体工作流示例：

录音节点 → [音频文件] → 声墨 HTTP 工具 → [转写文本] → 后续处理节点

当前能力边界

可通过 HTTP 完成

• 健康检查与状态查询
• 模型管理（下载、加载、卸载）
• 同步 / 异步语音转写
• 标点恢复后处理

目前需由调用方自行负责

• 麦克风打开与录音采集
• 录音开始 / 停止控制
• 结果复制到剪贴板或自动粘贴

这部分能力在完整桌面客户端中已内置，HTTP 独立模式下由外部程序负责。