soulshell-base 0.3.1

统一的多云服务聚合包，提供 ASR（语音识别）、TTS（语音合成）、OSS（对象存储）、RAG（检索增强生成）服务

SoulShell-Base

服务聚合项目，面向需要同时接入多家云服务的 Python 应用，提供统一的 ASR（语音识别）、TTS（语音合成）、OSS（对象存储）和 RAG（检索增强生成）接口。

项目特性

• 统一契约：通过工厂、请求模型、响应模型和异常类型收敛不同 Provider 的接入差异。
• 按需依赖：核心包保持轻量，云厂商 SDK 通过 extras 分组按需安装。
• 异步优先：ASR、TTS、OSS、RAG 的核心能力围绕 async/await 设计，便于接入服务端链路。
• 配置灵活：支持字典参数、环境变量占位符和配置文件组合使用。
• CLI 可用：内置 ASR 批量识别、TTS 批量合成和唤醒词音频生成命令。
• 发布友好：打包配置只发布运行时需要的源码、许可证、变更记录和项目入口文档。

环境要求

• Python 3.10+
• uv（推荐用于本地开发和验证）

安装

基础安装：

pip install soulshell-base

安装指定能力：

# TTS
pip install "soulshell-base[tts-azure]"
pip install "soulshell-base[tts-aliyun]"
pip install "soulshell-base[tts-volcengine-v1]"
pip install "soulshell-base[tts-volcengine-v3]"
pip install "soulshell-base[tts-xunfei]"
pip install "soulshell-base[tts-all]"

# ASR
pip install "soulshell-base[asr-volcengine]"
pip install "soulshell-base[asr-aliyun]"
pip install "soulshell-base[asr-xunfei]"
pip install "soulshell-base[asr-all]"

# OSS / RAG / 跨模块能力
pip install "soulshell-base[oss-aliyun]"
pip install "soulshell-base[oss-all]"
pip install "soulshell-base[rag-ragflow]"
pip install "soulshell-base[rag-all]"
pip install "soulshell-base[aliyun]"
pip install "soulshell-base[all]"

本地开发安装：

uv sync --extra dev

模块概览

模块	导入入口	主要能力	Provider
TTS	soulshell_base.tts	文本转语音、音色参数、批量合成支撑	Azure、阿里云、火山引擎、讯飞
ASR	soulshell_base.asr	音频识别、识别结果封装、批量测试支撑	火山引擎、阿里云、讯飞
OSS	soulshell_base.oss	文件上传、分片上传、元数据和访问 URL	阿里云 OSS
RAG	soulshell_base.rag	数据集、助理、会话、检索和对话	RagFlow
Cache	soulshell_base.cache	本地缓存区域、索引和原子写入	本地文件系统
Core	soulshell_base.core	日志、重试、工具函数和运行时状态	通用能力

快速示例

TTS

import asyncio

from soulshell_base.tts import TTSFactory, TTSSynthesizeRequest


async def main() -> None:
    tts = TTSFactory.create(
        provider_name="azure",
        api_key="your_api_key",
        endpoint="https://example.cognitiveservices.azure.com",
    )
    request = TTSSynthesizeRequest(
        text="你好世界",
        voice_id="zh-CN-XiaoxiaoNeural",
    )
    response = await tts.synthesize(request)
    print(response)


asyncio.run(main())

ASR

import asyncio

from soulshell_base.asr import ASRFactory, ASRRecognizeRequest, AudioFormat


async def main(audio_bytes: bytes) -> None:
    asr = ASRFactory.create(
        provider_name="volcengine",
        token="your_token",
        appid="your_appid",
    )
    request = ASRRecognizeRequest(
        audio_data=audio_bytes,
        language="zh-CN",
        audio_format=AudioFormat.WAV,
    )
    response = await asr.recognize(request)
    print(response)


asyncio.run(main(audio_bytes=b"..."))

Core

from soulshell_base.core import async_retry, get_logger

logger = get_logger(__name__)


@async_retry(max_attempts=3, delay=1.0)
async def call_remote_service() -> None:
    logger.info("calling remote service")

配置约定

Provider 支持直接传入参数，也可配合 JSON 配置和环境变量占位符使用。常见占位符格式：

${VAR_NAME}
${VAR_NAME:default_value}

示例配置：

{
  "provider_name": "azure",
  "api_key": "${AZURE_API_KEY}",
  "endpoint": "${AZURE_ENDPOINT}",
  "voice_id": "${AZURE_VOICE_ID:zh-CN-XiaoxiaoNeural}",
  "encoding": "wav",
  "sample_rate": 16000
}

CLI

安装后提供以下命令：

soulshell-asr --help
soulshell-tts --help
soulshell-tts-wakegen --help

也可以使用模块方式调用：

python -m soulshell_base.cli.asr --help
python -m soulshell_base.cli.tts --help
python -m soulshell_base.cli.tts_wakegen --help

开发与验证

常用本地验证命令：

uv sync --extra dev
uv run --extra dev pytest test/test_packaging_metadata.py -q
uv run ruff check src test

涉及真实云服务的集成路径需要先配置对应环境变量；没有明确需要时，优先运行不触网的契约测试和元数据测试。

贡献

1. 创建特性分支。
2. 保持改动范围聚焦，并遵循现有模块边界。
3. 补充或更新对应测试与文档。
4. 确认发布元数据测试和必要验证通过。
5. 提交 Pull Request。

许可证

MIT License。