服务器使用说明

环境要求

项目	要求
操作系统	Linux (Ubuntu 20.04+) / macOS 12+ / Windows 10+
Python	3.11+
内存	推荐 4GB+, 如果运行本地模型需根据模型要求配置对应内存
FFmpeg	必需
Opus 编解码器	必需
Playwright	可选（用于电子书搜索功能）

快速部署

bash

# 1. 克隆项目
git clone https://github.com/nephilimbin/lingzhi.git
cd lingzhi

# 2. 创建并激活 Python 环境
conda create -n lingzhi python=3.11
conda activate lingzhi

# 3. 安装依赖
cd server
pip install -r requirements.txt

# 4. 生成开发环境 SSL 证书（开启 SSL 时需要）
bash scripts/generate_ssl_cert.sh

# 5. 配置服务参数
cp config/.server_config_example.yaml config/.server_config.yaml
# 编辑 .server_config.yaml 配置文件

# 6. 启动服务
python app.py

安装其他工具依赖

bash

# 安装 FFmpeg
# Ubuntu/Debian
sudo apt update
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Windows
# 从 https://ffmpeg.org/download.html 下载并添加到环境变量 PATH

bash

# 安装 Opus 编解码器
# Ubuntu/Debian
sudo apt update
sudo apt install libopus-dev

# macOS
# 安装Homebrew（如果尚未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install opus

# Windows
# 从 https://opus-codec.org/downloads/ 下载并添加到环境变量 PATH

服务端点

端点	协议	说明
`/`	HTTP	服务首页
`/chat/v1/`	WebSocket	聊天连接端点
`/api/v1/health`	HTTP	健康检查
`/api/v1/config/`	HTTP	配置管理
`/docs`	HTTP	API 文档

配置文件说明

配置文件位于 server/config/.server_config.yaml，以下为详细参数说明。

服务器基础配置 (server)

server 基础参数

参数	类型	必要	默认值	说明
`server.ip`	string	是	`0.0.0.0`	服务器监听地址，`0.0.0.0` 表示监听所有网卡
`server.port`	integer	是	`8000`	服务器监听端口
`server.app.title`	string	否	`零知`	应用名称
`server.app.description`	string	否	-	应用描述
`server.app.version`	string	是	`1.0.0`	应用版本号，暂未做版本管理，后期会添加

SSL 配置 (server.ssl)

参数	类型	必要	默认值	说明
`enabled`	boolean	是	`true`	是否启用 SSL 加密连接（启用后使用 `wss://` 协议）
`cert_path`	string	是	`certs/server.crt`	SSL 证书文件路径（相对于项目根目录）
`key_path`	string	是	`certs/server.key`	SSL 私钥文件路径（相对于项目根目录）
`ssl_version`	string	否	`TLSv1_2`	SSL 版本，可选：`TLSv1_2`、`TLSv1_3`
`verify_client`	boolean	否	`false`	是否验证客户端证书（双向认证）
`ca_cert_path`	string	否	`certs/ca.crt`	CA 证书路径（仅在 `verify_client` 为 `true` 时需要）

*仅在 enabled: true 时必要

认证配置 (server.auth)

参数	类型	必要	默认值	说明
`enabled`	boolean	是	`false`	是否启用设备认证。如果为启用，需要先在后端配置设备及对应Token; 如果不启用，下方配置将被忽略
`tokens`	array	是	-	设备 Token 列表
`tokens[].token`	string	是	-	认证令牌
`tokens[].name`	string	是	-	设备 MAC 地址（用于绑定设备）
`allowed_devices`	array	否	-	设备白名单（MAC 地址列表）

*仅在 enabled: true 时必要

Token 配置示例：

yaml

auth:
  enabled: true
  tokens:
    - token: 'your_token_here'
      name: '8a:b8:92:43:d3:de'  # 设备 MAC 地址
    - token: 'another_token'
      name: '5b:87:b1:bf:2c:f8'

代理配置 (server.proxy)

参数	类型	必要	默认值	说明
`http_proxy`	string	否	-	HTTP 代理地址
`https_proxy`	string	否	-	HTTPS 代理地址

WebRTC 配置 (server.webrtc)

参数	类型	必要	默认值	说明
`ice_candidate_pool_size`	integer	否	`4`	ICE 候选池大小
`ice_transport_policy`	string	否	`all`	ICE 传输策略，可选：`all`、`relay`
`bundle_policy`	string	否	`max-bundle`	Bundle 策略，可选：`max-bundle`、`max-compat`、`balanced`
`rtcp_mux_policy`	string	否	`require`	RTCP 复用策略，可选：`require`、`negotiate`
`ice_servers`	array	否	-	ICE 服务器列表
`ice_servers[].urls`	array	是	-	STUN/TURN 服务器地址列表
`ice_servers[].username`	string	否	-	TURN 服务器用户名
`ice_servers[].credential`	string	否	-	TURN 服务器凭证

仅在电话实时对话模式下需要配置, 这里我使用的是 Cloudflare 的 STUN/TURN 服务器，免费额度很充足。

yaml

webrtc:
  ice_servers:
    - urls:
        - 'stun:stun.cloudflare.com:3478'
        - 'turn:turn.cloudflare.com:3478?transport=udp'
        - 'turn:turn.cloudflare.com:3478?transport=tcp'
        - 'turns:turn.cloudflare.com:5349?transport=tcp'
      username: 'YOUR_TURN_USERNAME' # [TURN必填] TURN服务器用户名
        credential: 'YOUR_TURN_CREDENTIAL' # [TURN必填] TURN服务器凭证

日志配置 (log)

参数	类型	必要	默认值	说明
`log_format`	string	否	-	控制台日志格式
`log_format_file`	string	否	-	文件日志格式
`log_level`	string	否	`DEBUG`	日志级别，可选：`DEBUG`、`INFO`、`WARNING`、`ERROR`
`log_dir`	string	否	`log`	日志文件目录
`log_file`	string	否	`server.log`	日志文件名
`data_dir`	string	否	`data`	数据文件目录

该项参数建议不要随意改动，除非你了解这些参数的含义。对排查bug很有帮助。

对话配置

参数	类型	必要	默认值	说明
`tts_silent_timeout_shutdown_duration`	integer	否	`120`	无语音输入后断开连接的超时时间（秒）
`silence_threshold_ms`	integer	否	`1000`	VAD 静默阈值（毫秒）
`dialogue_context_num`	integer	否	`20`	对话上下文保留条数

模型选择配置 (selected_module)

参数	类型	必要	默认值	说明
`VAD`	string	是	`SileroVAD`	语音活动检测模块
`ASR`	string	是	`FunASR_Docker`	语音识别模块
`LLM`	string	是	-	大语言模型模块
`TTS`	string	是	-	语音合成模块
`Memory`	string	是	`nomem`	记忆模块, 暂时不支持记忆搜索或长期记忆功能，只能调整上下文对话条数来控制对话，后期会优化完善该模块。
`Intent`	string	是	-	意图识别模块，再大模型最终回复前会判断是否调用工具等。非长任务Agent功能，后期会完善该模块。
`VLM`	string	是	-	视觉语言模型模块

所有具体选择或使用的模型都支持自定义，根据基类实现抽象方法即可。参数均可自行调整或配置。

ASR 语音识别配置

FunASR_Docker

参数	类型	必要	默认值	说明
`type`	string	是	`funasr_docker`	类型标识
`nickname`	string	否	-	显示名称
`base_url`	string	是	`ws://127.0.0.1:10095`	Docker 服务地址
`fallback_to_ws`	boolean	否	`true`	WSS 失败时是否尝试 WS
`model_name`	string	是	`SenseVoiceSmall`	模型名称

QwenASR

参数	类型	必要	默认值	说明
`type`	string	是	`qwen`	类型标识
`nickname`	string	否	-	显示名称
`model_name`	string	是	`gummy-realtime-v1`	模型名称
`api_key`	string	是	-	通义千问 API Key

TTS 语音合成配置

QwenTTS

参数	类型	必要	默认值	说明
`type`	string	是	`qwen`	类型标识
`voice`	string	是	`Cherry`	发音人
`model_name`	string	是	`qwen3-tts-flash-realtime`	模型名称
`api_key`	string	是	-	通义千问 API Key
`base_url`	string	否	`wss://dashscope.aliyuncs.com/api-ws/v1/realtime`	API 地址
`language_type`	string	否	`Auto`	语言类型
`sample_rate`	integer	否	`24000`	采样率

EdgeTTS（免费）

参数	类型	必要	默认值	说明
`type`	string	是	`edge`	类型标识
`voice`	string	是	`zh-CN-XiaoxiaoNeural`	发音人
`model_name`	string	否	`official`	模型名称

LLM 大语言模型配置

智谱 GLM

参数	类型	必要	默认值	说明
`type`	string	是	`zhipu`	类型标识
`api_key`	string	是	-	智谱 API Key
`model_name`	string	是	`glm-4.5`	模型名称
`max_output_tokens`	integer	否	`8192`	最大输出 Token 数
`temperature`	float	否	`0.2`	温度参数 (0-1)
`thinking_mode`	string	否	`disabled`	思考模式，可选：`enabled`、`disabled`
`stream_mode`	boolean	否	`true`	是否启用流式输出

Ollama（本地）

参数	类型	必要	默认值	说明
`type`	string	是	`ollama`	类型标识
`model_name`	string	是	`qwen2.5`	模型名称（需预先 `ollama pull`）
`base_url`	string	是	`http://localhost:11434`	Ollama 服务地址

Memory 记忆模块配置

模块名	type	说明
`nomem`	`nomem`	不使用记忆功能（默认）

插件配置 (function_plugins)

音乐播放 (play_music)

参数	类型	必要	默认值	说明
`music_dir`	string	是	`./music`	音乐文件存放路径
`music_ext`	array	否	-	音乐文件扩展名
`refresh_time`	integer	否	`300`	刷新列表间隔（秒）

电影搜索 (search_movie)

参数	类型	必要	说明
`base_url`	string	是	服务地址
`password`	string	是	访问密码

电子书搜索 (search_ebook)

参数	类型	必要	说明
`domains`	array	是	Z-Library 域名列表
`email`	string	是	登录账号
`password`	string	是	登录密码

其他配置

唤醒词配置

参数	类型	必要	默认值	说明
`enable_wakeup_words_response`	boolean	否	`true`	是否启用唤醒词响应
`wakeup_words`	array	否	-	唤醒词列表
`wakeup_words_notify_voice`	string	否	-	唤醒回复音频路径

退出命令

参数	类型	必要	默认值	说明
`cmd_exit`	array	否	`['退出', '关闭', '停止', '结束', '暂停']`	退出命令词列表, 可中断正在执行的任务且无任何返回结果。

模板文件

参数	类型	必要	说明
`system_prompt_template`	string	否	系统提示词模板路径, 默认使用 `server/prompts/system_prompt.txt`
`intent_prompt_template`	string	否	意图识别提示词模板路径, 默认使用 `server/prompts/intent_prompt.txt`

常见问题

证书生成

开启 SSL 需要先生成证书，执行：

bash

bash scripts/generate_ssl_cert.sh

证书将生成在 server/certs/ 目录下。

安全提示

请勿将 .server_config.yaml 文件提交到版本控制
生产环境建议启用 SSL 和认证
API Key 等敏感信息请妥善保管

服务器使用说明 ​

环境要求 ​

快速部署 ​

安装其他工具依赖 ​

服务端点 ​

配置文件说明 ​

服务器基础配置 (server) ​

server 基础参数 ​

SSL 配置 (server.ssl) ​

认证配置 (server.auth) ​

代理配置 (server.proxy) ​

WebRTC 配置 (server.webrtc) ​

日志配置 (log) ​

对话配置 ​

模型选择配置 (selected_module) ​

ASR 语音识别配置 ​

FunASR_Docker ​

QwenASR ​

TTS 语音合成配置 ​

QwenTTS ​

EdgeTTS（免费） ​

LLM 大语言模型配置 ​

智谱 GLM ​

Ollama（本地） ​

Memory 记忆模块配置 ​

插件配置 (function_plugins) ​

音乐播放 (play_music) ​

电影搜索 (search_movie) ​

电子书搜索 (search_ebook) ​

其他配置 ​

唤醒词配置 ​

退出命令 ​

模板文件 ​

常见问题 ​

服务器使用说明

环境要求

快速部署

安装其他工具依赖

服务端点

配置文件说明

服务器基础配置 (server)

server 基础参数

SSL 配置 (server.ssl)

认证配置 (server.auth)

代理配置 (server.proxy)

WebRTC 配置 (server.webrtc)

日志配置 (log)

对话配置

模型选择配置 (selected_module)

ASR 语音识别配置

FunASR_Docker

QwenASR

TTS 语音合成配置

QwenTTS

EdgeTTS（免费）

LLM 大语言模型配置

智谱 GLM

Ollama（本地）

Memory 记忆模块配置

插件配置 (function_plugins)

音乐播放 (play_music)

电影搜索 (search_movie)

电子书搜索 (search_ebook)

其他配置

唤醒词配置

退出命令

模板文件

常见问题