African Speech Corpora Quality Audit

非洲语音语料 MCP

一个只读服务，通过公开的非洲语言语音语料实现 Model Context Protocol。该协议是由 Anthropic 创建的开放标准。语料目前以沃洛夫语为主，另包括富拉语和塞雷尔语。

本项目以沃洛夫语为主。2.0 目录包含 14 个变体：11 个原始来源变体和 3 个衍生变体。富拉语（ful）和塞雷尔语（srr）仅包含 Kallaama 变体，且没有本地指标；本项目不声称覆盖斯瓦希里语或阿姆哈拉语。随附的验证锁定文件生成于 2026 年 8 月 26 日，其中 6 个 Hugging Face 变体可供查询。后续验证运行自然可能产生不同状态。

2.0.0 版本发布于 PyPI，并以 io.github.papasega/african-speech-corpora 的名称发布于官方 MCP Registry。

该服务不会训练模型、下载完整语料，也不会向 Hugging Face、OpenSLR、Kaggle、GitHub 或任何其他远程来源写入数据。

服务测量的内容

质量管线将以下阶段分别处理：

raw audio → usable audio → transcribed audio → audit-accepted audio → expert-verified audio

• 原始：观测快照中存在的文件。
• 可用：经过审计中可量化的排除项筛选后保留的文件。
• 已转录：带有转录文本的音频。
• 审计认可：明确命名的并集，包括专家验证的材料，以及审计仅假定有效的材料。
• 专家验证：仅包括 expert_audited 或 source_reported_expert。“先验”评估绝不会纳入此级别。

秒是标准时长表示形式。十进制小时和 HH:MM:SS 字符串在序列化时推导得出。每项已审计指标都会注明其范围、来源、方法、观测日期和置信度。缺失值仍为 null，绝不会转换为零。项目发布的数据保留在 published_metrics 中，与本地观测数据分开。

2026 年沃洛夫语快照

机器可读的源文件是 assets/wolof-audit-2026.csv。协议、局限性以及与源表 TOTAL 单元格的差异记录在 assets/wolof-audit-2026.md 中。

七种沃洛夫语变体有本地观测数据：ALFFA、FLEURS wo_sn、Kallaama Wolof、Urban Bus、Waxal 众包数据、Wolof TTS Baamtu 和 WolBanking77。总数根据这七行重新计算，不会另行存储冗余的手动总数：148,102 个可用文件、64,609 个已转录文件、50,494 个通过审计的文件、2,329,382.06 秒音频、515,185.06 秒已转录音频，以及 302,048.06 秒通过审计的音频。

重要局限性：

• FLEURS、Urban Bus、Waxal、Wolof TTS 和 WolBanking77 中标为“先验”的观测属于 audit_assumed_valid，并非经专家验证；
• 此快照明确显示 ALFFA 的经专家验证文件数为零；
• 153 个 Kallaama 文件是较长的广播或访谈录音，并非 153 段语音轮次；其中 36 个文件和 12:49:36 的时长依据本地协议的 source_reported_expert 口径统计；
• Urban Bus 含有大量法语内容，但没有量化其占比，因此其 language_purity=mixed_fr；
• Waxal 将 517:38:05 的原始音频（尤其适用于 SSL）与仅供监督式 ASR 使用的 13:41:28 已转录音频区分开来；
• 本地 Wolof TTS Baamtu 快照包含 36,009 个文件和 37:04:49 音频，与四舍五入后的公开指标不同；默认情况下，此 TTS 语料库不纳入 ASR；
• WolBanking77 区分了观测到的 2,563 个音频文件和其他来源报告的 9,791 条文本短语；
• Afrivoice 发布了 530.74 小时的沃洛夫语音频，其中包括 102.96 小时的已转录音频。这些是来源发布的数据，并非 2026 年本地审计的测量结果，也不能作为经专家验证的证据。该数据集在 Hugging Face 上设有自动门控，因此若不接受其访问条件并提供令牌，就无法独立核查其文件、架构、数据拆分和时长；因此其状态仍为 audit_status=pending；
• 由于无法获取确切的来源观测日期，observed_at=2026 有意仅精确到年份。

安装

此软件包需要 Python 3.11 或更高版本。推荐使用 Python 3.12，并在下文明确指定，以免虚拟环境意外沿用 Python 3.9 等较旧的系统解释器：

从 PyPI 安装已发布的版本：

python3.12 --version
python3.12 -m venv .venv
source .venv/bin/activate
python --version
python -m pip install "african-speech-mcp==2.0.0"

用于开发时，请检出代码并以可编辑模式安装开发依赖：

git clone https://github.com/papasega/african-speech-mcp.git
cd african-speech-mcp
python3.12 --version
python3.12 -m venv .venv
source .venv/bin/activate
python --version
python -m pip install -e ".[dev]"

两个版本命令都应显示 Python 3.12.x。只有在 python 可执行文件对应的版本已是 Python 3.11 或更高时，使用 python -m venv .venv 创建环境才是安全的。如果安装失败并出现类似以下错误：

ERROR: Package 'african-speech-mcp' requires a different Python: 3.9.6 not in '>=3.11'

说明虚拟环境是使用 Python 3.9.6 创建的。请停用该环境，删除或重命名本地 .venv，必要时安装 Python 3.12，然后使用 python3.12 -m venv .venv 重新创建环境。虚拟环境会保留创建时使用的解释器；激活环境不会升级 Python。

stdio 服务无需参数即可启动：

african-speech-mcp

也可以显式启动：

african-speech-mcp serve --transport stdio
african-speech-mcp serve --transport streamable-http

安装软件包后的 Claude Desktop 配置示例，建议使用绝对路径：

{
  "mcpServers": {
    "african-speech-corpora": {
      "command": "/absolute/path/to/.venv/bin/african-speech-mcp"
    }
  }
}

2.0.0 版本已发布到 PyPI，可使用 pip 安装。开发或使用尚未发布的更改时，应选择从仓库安装。

MCP 工具

所有 8 个工具均声明 read_only_hint=true、destructive_hint=false 和 idempotent_hint=true。

工具	用途
list_corpora	列出各变体、审计状态、推荐用途和验证状态。
audit_corpus	返回数量、时长、验证依据、警告以及单独发布的统计数据。
plan_training_set	制定计划，不重复计算衍生数据集，也不默认纳入基准测试集。
filter_segments	仅在存在行级清单时进行筛选；否则拒绝承诺排除内容。
compare_corpora	比较质量、领域、语言纯度、许可证和指标时效性。
search_segments	在远程架构已通过验证的变体中搜索行。
corpus_stats	仅返回该变体配置的大小，并报告架构差异。
cite_corpus	返回衍生数据集的许可证、引文及其父级引文。

概念示例：

audit_corpus(corpus="waxal-crowdsource")

plan_training_set(language="wol", task="asr", quality="transcribed")
plan_training_set(language="wol", task="asr", quality="expert_verified")
plan_training_set(
  language="wol",
  task="asr",
  quality="audit_accepted",
  include_mixed_language=true,
)

filter_segments(
  corpus="waxal-crowdsource",
  exclude_duplicates=true,
  exclude_non_wolof=true,
  exclude_corrupt=true,
)

最后一次调用目前返回 filter_available=false。汇总数据表明，Waxal 包含 430 个重复文件和 22 个损坏或非沃洛夫语文件，但没有提供行标识符。因此，服务不会假装自己移除了这些行。

plan_training_set 的语义

quality 支持以下值：

• any：按任务和许可证选择，无需转录；
• transcribed：使用实际转录时长；
• audit_accepted：纳入专家验证和默认有效的材料，并显示明细和警告；
• expert_verified：仅使用真正经过专家验证的依据；
• wolof_only：排除 mixed_fr、mixed、unknown 以及缺乏充分语言纯度证据的变体。

metric_source 可以是 latest_audit（默认值）或 published。时长未知的变体仍会列在 hours_unknown_for 中。FLEURS 是基准测试集，除非设置 include_benchmarks=true，否则不会纳入训练。使用 Urban Bus 必须设置 include_mixed_language=true。除非明确启用，否则 TTS 变体不会纳入 ASR；衍生数据集也绝不会添加到其父级数据集中。未知、非商业、相同方式共享或未经确认的许可证会触发相应警告；commercial_use=null 绝不会被标示为兼容商业用途。

持久化的 Hugging Face 验证

african-speech-mcp validate
african-speech-mcp validate --write
african-speech-mcp validate --output validation-lock.json

验证会检查数据集标识符、配置、拆分、转录列，以及任何已声明的语言列。锁定文件通过原子替换写入，并记录 checked_at、观测到的架构信息和稳定指纹。该文件还会绑定目录哈希，因此服务会拒绝过期的锁定文件。

默认情况下，--write 会在当前目录中创建 validation-lock.json，而不会修改已安装的软件包。之后可通过以下方式使用：

export ASM_VALIDATION_LOCK_PATH="$PWD/validation-lock.json"
african-speech-mcp

可能的状态包括 unverified、verified、gated、unavailable、schema_mismatch 和 quality_blocked。如果预期配置或列缺失，即使标识符有响应，也绝不会将其标记为 verified。对于 Afrivoice，请在验证前在本地设置 ASM_HF_TOKEN；该令牌不会被序列化或记录到日志中。

corpus_stats 严格按配置筛选，因此 FLEURS wo_sn 绝不会包含其他语言的数据。没有单独配置的多语言分布必须声明语言列和可接受的值。当服务无法保证筛选结果时，会拒绝请求或返回明确警告。

目录与架构

src/african_speech_mcp/
├── audit.py              # audited CSV, duration formats, deterministic aggregation
├── catalog.py            # Pydantic v2 variants and invariants
├── cli.py                # serve, validate, catalog-show
├── config.py             # ASM_* settings
├── hf_client.py          # GET only, retries, bounded concurrency
├── models.py             # structured responses
├── server.py             # eight MCP tools
├── validation.py         # schema inspection and atomic lock files
└── data/
    ├── corpora.json      # single canonical catalog
    └── validation-lock.json

根目录下不再有第二份 corpora.json。审计 CSV 仍以 assets/ 下的文件为准，且 Hatch 会确定性地将其纳入 wheel。测试会检查 CSV 与目录之间的总数和引用关系。

常用变量包括 ASM_CATALOG_PATH、ASM_VALIDATION_LOCK_PATH、ASM_AUDIT_LOG_PATH、ASM_HF_TOKEN、ASM_REQUEST_TIMEOUT_S、ASM_REQUEST_RETRIES 和 ASM_VALIDATION_CONCURRENCY。运行时日志会写入 stderr，以便 stdout 保留给 stdio 协议。

贡献审计或清单

新增审计必须：

1. 在 CSV 中添加单元行，不得手动添加 TOTAL 行；
2. 提供 audit_id、observed_at、source_reference、method、confidence 和 verification basis；
3. 区分观测到的零值和缺失值；
4. 在匹配的变体中引用该审计；
5. 使用 Markdown 记录限制，并添加一致性测试。

若要启用实际筛选，请提供带版本号的清单，至少包含：

audit_id,corpus_key,revision,row_id,audio_path,is_duplicate,is_empty,is_corrupt,is_wolof,transcript_quality,reason

标识符必须来自经过审计的快照。绝不能根据汇总计数臆造标识符。

开发和发布准备

python -m pip install -e ".[dev]"
ruff check src tests scripts
pytest -q
python -m build

CI 会在 Python 3.11 和 3.12 上运行这些检查，在干净的环境中安装构建好的 wheel，并测试 CLI 和真实的 MCP stdio 交互。版本 2.0.0 是一次有文档记录的不兼容版本：现在，公共单元是单语言、单任务、单配置的变体，并提供了结构更丰富的质量响应。

发布非预发布版的 GitHub Release 会运行 .github/workflows/publish-pypi.yml。该工作流会验证附加的分发包，通过 Trusted Publishing 将其发布到 PyPI，然后验证匹配的 server.json，并通过 GitHub OIDC 将其发布到官方 MCP Registry。不存储任何长期有效的 PyPI 或 MCP Registry 令牌。如果 PyPI 发布成功但注册表步骤失败，请使用相同的标签手动重新运行工作流，并设置 registry_only=true；如果检测到已处于活动状态的注册表版本，则会将其视为成功。

许可证

服务代码根据 Apache-2.0 许可证授权。每个语料库均保留其自身的许可证。标记为 TO BE CONFIRMED 或 SEE DATASET ... 的目录条目有意保持不确定，使用前必须根据主要来源进行核实，尤其是用于商业用途时。