Alfanous - Quranic Search Engine

Alfanous API

Alfanous 是一个《古兰经》搜索引擎 API，提供简单和高级搜索功能。它支持开发者构建可搜索阿拉伯语《古兰经》文本的应用，并支持 Buckwalter 转写、高级查询语法和丰富的元数据。

功能

• 强大的搜索：使用简单查询或高级布尔逻辑搜索《古兰经》经文
• 阿拉伯语支持：全面支持阿拉伯语文本和 Buckwalter 转写
• 丰富的元数据：获取经文信息、译文、诵读和语言学数据
• 灵活的 API：可用作 Python 库或 RESTful Web 服务
• 分面搜索：按《古兰经》章（Sura）、Juz、主题等汇总结果
• 多种输出格式：通过不同的视图和高亮样式自定义输出

快速开始

安装

使用 pip 从 PyPI 安装：

$ pip install alfanous3

基本用法

Python 库

>>> from alfanous import api

# Simple search for a word
>>> api.search(u"الله")

# Advanced search with options
>>> api.do({"action": "search", "query": u"الله", "page": 1, "perpage": 10})

# Search using Buckwalter transliteration
>>> api.do({"action": "search", "query": u"Allh"})

# Get suggestions
>>> api.do({"action": "suggest", "query": u"الح"})

# Correct a query
>>> api.correct_query(u"الكتاب")

# Get metadata information
>>> api.do({"action": "show", "query": "translations"})

Web 服务

你也可以使用公共 Web 服务：

• 搜索：http://alfanous.org/api/search?query=الله
• 使用转写搜索：http://alfanous.org/api/search?query=Allh

或者在本地运行自己的 Web 服务（参见 alfanous_webapi）。

快速示例

搜索短语：

>>> api.search(u'"الحمد لله"')

布尔搜索（AND、OR、NOT）：

>>> api.search(u'الصلاة + الزكاة')    # AND
>>> api.search(u'الصلاة | الزكاة')    # OR
>>> api.search(u'الصلاة - الزكاة')    # NOT

字段搜索：

>>> api.search(u'سورة:يس')           # Search in Sura Yasin
>>> api.search(u'سجدة:نعم')          # Search verses with sajda

通配符搜索：

>>> api.search(u'*نبي*')             # Words containing "نبي"

分面搜索（按字段汇总）：

>>> api.do({
...     "action": "search",
...     "query": u"الله",
...     "facets": "sura_id,juz"
... })

文档

API 参考

核心函数

• api.search(query, **options) - 搜索《古兰经》经文
• api.do(params) - 所有操作（search、suggest、show、list_values、correct_query）的统一接口
• api.correct_query(query, unit, flags) - 获取拼写纠正后的查询
• api.get_info(category) - 获取元数据信息

底层的 Raw 输出引擎在 alfanous.api 中以 Engine 的形式提供（也可直接从 alfanous 重新导出）。将其用作上下文管理器，以确保正确释放索引资源：

from alfanous.api import Engine
# or equivalently:
# from alfanous import Engine

with Engine() as engine:
    result = engine.do({"action": "search", "query": u"الله"})

搜索参数

api.do() 中 action="search" 的常用参数：

• query（str）：搜索查询（必需）
• unit（str）：搜索单元——"aya"、"word" 或 "translation"（默认值："aya"）
• page（int）：页码（默认值：1）
• perpage（int）：每页结果数，范围为 1-100（默认值：10）
• sortedby（str）：排序方式——"score"、"relevance"、"mushaf"、"tanzil"、"ayalength"（默认值："score"）
• reverse（bool）：反转排序顺序（默认值：False）
• view（str）：输出视图——"minimal"、"normal"、"full"、"statistic"、"linguistic"（默认值："normal"）
• highlight（str）：高亮样式——"css"、"html"、"bold"、"bbcode"（默认值："css"）
• script（str）：文本书写形式——"standard" 或 "uthmani"（默认值："standard"）
• vocalized（bool）：包含阿拉伯语元音符号（默认值：True）
• translation（str）：要包含的译文 ID
• recitation（str）：要包含的诵读 ID（1-30，默认值："1"）
• fuzzy（bool）：启用模糊搜索——同时搜索 aya_（精确）和 aya（已规范化／词干提取）字段，并进行 Levenshtein 距离匹配（默认值：False）。参见精确搜索与模糊搜索。
• fuzzy_maxdist（int）：模糊词条匹配的最大 Levenshtein 编辑距离——1、2 或 3（默认值：1，仅在 fuzzy=True 时使用）。
• facets（str）：用于分面搜索的逗号分隔字段列表
• filter（dict）：按字段值筛选结果

完整的参数和选项列表请参见详细文档。

高级功能

精确搜索与模糊搜索

Alfanous 提供两种互补的搜索模式，用于控制查询哪些索引字段。

精确搜索（默认 — fuzzy=False）

关闭模糊搜索（默认状态）时，查询会针对 aya_ 字段运行。该字段存储完整保留变音符号（tashkeel）的《古兰经》文本。此模式专为精确的统计匹配而设计：

• 查询中的变音符号会影响匹配结果 — مَلِكِ 和 مَالِكِ 会被视为不同的词。
• 查询不会进行停用词移除、同义词扩展或词干提取。
• 适用于需要精确短语匹配、可复现的结果数量或统计分析的情况。

# Default exact search — only the vocalized aya_ field is used
>>> api.search(u"الله")
>>> api.search(u"الله", fuzzy=False)

# Phrase match with full diacritics
>>> api.search(u'"الْحَمْدُ لِلَّهِ"')

模糊搜索（fuzzy=True）

启用模糊搜索时，查询会同时针对 aya_ 字段（精确匹配）和 aya 字段（为宽泛、宽容的搜索单独构建的索引）运行。在建立索引时，aya 字段会经过更丰富的处理流程：

1. 规范化 — 统一变形字母、tatweel、hamza 变体和常见拼写错误。
2. 停用词移除 — 过滤掉高频功能词（例如 مِنْ、فِي、مَا），避免其降低结果相关性。
3. 同义词扩展 — 每个词元都会与其同义词一并存储，因此查询某个词时会自动匹配同义词。
4. 阿拉伯语词干提取 — 使用 Snowball 阿拉伯语词干提取器（通过 pystemmer）将词还原为词干，使同一词根的不同形态能够相互匹配。

搜索时不会对查询字符串执行复杂操作；所有语言处理都在索引中完成。

此外，针对查询中的每个阿拉伯语词项，系统都会在 aya_ac 字段（未标音、未提取词干）上执行 Levenshtein 距离搜索。这能在由 fuzzy_maxdist 控制的可配置编辑距离范围内，捕获拼写变体和错别字。

# Fuzzy search — aya_ (exact) + aya (normalised/stemmed) + Levenshtein distance on aya_ac
>>> api.search(u"الكتاب", fuzzy=True)

# Increase edit distance to 2 to tolerate more spelling variation
>>> api.search(u"الكتاب", fuzzy=True, fuzzy_maxdist=2)

# Via the unified interface
>>> api.do({
...     "action": "search",
...     "query": u"مؤمن",
...     "fuzzy": True,
...     "fuzzy_maxdist": 1,
...     "page": 1,
...     "perpage": 10
... })

fuzzy_maxdist	行为
1（默认）	捕获单字符插入、删除或替换
2	更宽泛的容错范围 — 适用于较长的词或有噪声的输入
3	支持的最大值 — 请谨慎使用，因为召回率会显著提高

以下情况特别适合使用模糊模式：

• 用户不知道某个词的确切标音形式。
• 希望形态相关的词出现在同一结果集中（例如，搜索 كتب 也会显示 كتاب、كاتب、مكتوب）。
• 希望在无需编写显式 OR 查询的情况下，进行同义词感知检索。

注意： 必须安装 pystemmer 才能启用词干提取（pip install pystemmer）。如果缺少此软件包，词干过滤器会静默退化为空操作，但规范化和停用词移除仍然有效。

列出字段值

list_values 会返回给定字段中所有唯一的索引值。可用它来发现可搜索字段的完整词汇表 — 例如，在编写查询前查看所有可用的译文标识符、词性标签或词根。

# Get all unique root values in the index
>>> api.do({"action": "list_values", "field": "root"})
# Returns: {"list_values": {"field": "root", "values": [...], "count": N}}

# Discover all indexed translation IDs
>>> api.do({"action": "list_values", "field": "trans_id"})

# Discover all part-of-speech categories for word search
>>> api.do({"action": "list_values", "field": "pos"})

# Retrieve all indexed lemmas on demand (replaces the former show/lemmas)
>>> api.do({"action": "list_values", "field": "lemma"})

参数：

• field（str）：要获取其唯一值的索引字段名称（必填）。

返回值：

一个包含 list_values 键的字典，其中包括：

• field — 请求的字段名称。
• values — 已排序的非空唯一索引值列表。
• count — values 列表的长度。

查询纠错

correct_query() 使用 Whoosh 内置的拼写检查器，将查询中的每个词与索引词汇进行比较，并将未知词替换为最接近的已知词。如果查询本身有效（所有词都出现在索引中），响应中的 corrected 值与原始输入相同。

# Correct a query via the dedicated function
>>> api.correct_query(u"الكتاب")
# Returns:
# {"correct_query": {"original": "الكتاب", "corrected": "الكتاب"}, "error": ...}

# Correct a misspelled / out-of-vocabulary term
>>> api.correct_query(u"الكتب")
# Returns:
# {"correct_query": {"original": "الكتب", "corrected": "الكتاب"}, "error": ...}

# Via the unified interface
>>> api.do({"action": "correct_query", "query": u"الكتب", "unit": "aya"})

参数：

• query（str）：要纠正的原始查询字符串（必填）。
• unit（str）：搜索单元——目前仅支持 "aya"；其他单元会返回 None（默认值："aya"）。
• flags（dict）：可选的附加标记字典。

返回值：

包含 correct_query 键的字典，其中包括：

• original —— 按原样提供的输入查询字符串。
• corrected —— 纠正后的查询字符串；无需纠正时与 original 相同。

查询语法

Alfanous 支持高级查询语法：

• 短语：使用引号 - "الحمد لله"
• 布尔 AND：使用 + - الصلاة + الزكاة
• 布尔 OR：使用 | - الصلاة | الزكاة
• 布尔 NOT：使用 - - الصلاة - الزكاة
• 通配符：使用 * 表示多个字符，使用 ? 表示单个字符 - *نبي*、نعم؟
• 字段搜索：使用字段名 - سورة:يس、سجدة:نعم
• 范围：使用 [X الى Y] - رقم_السورة:[1 الى 5]
• 部分元音符号：使用部分变音符号进行搜索 - آية_:'مَن'
• 派生形式（词干）：使用 > - >رحيم（搜索 aya_stem — 基于语料库派生的词干）
• 派生形式（词元）：使用 >> - >>رحيم（搜索 aya_lemma — 同一词位的所有屈折形式）
• 派生形式（词根）：使用 >>> - >>>ملك（搜索 aya_root — 同一词根的所有词语）
• 元组：使用 {root,type} - {قول،اسم}

派生层级搜索

使用 derivation_level 参数控制搜索在形态学层面的扩展范围：

层级	值	索引字段	描述
0	"word"	aya	仅精确匹配（默认）
1	"stem"	aya_stem	基于语料库派生的词干 — 共享同一形态词干的词语
2	"lemma"	aya_lemma	语料库词元 — 同一词位的所有屈折形式
3	"root"	aya_root	三辅音词根 — 同一词根的所有词语

每个派生字段在构建时都会预先编入索引，因此查询会针对紧凑的预计算表示执行，而不是在搜索时扩展。

# Level 0 — exact match
>>> api.do({"action": "search", "query": "رَحِيمٌ"})

# Level 1 — stem (corpus-derived stem)
>>> api.do({"action": "search", "query": "رحيم", "derivation_level": 1})

# Level 2 — all words sharing the same lemma (e.g. all forms of رَحِيمٌ)
>>> api.do({"action": "search", "query": "رحيم", "derivation_level": 2})

# Level 3 — all words from root رحم (رحمة، رحمن، رحيم، يرحم، …)
>>> api.do({"action": "search", "query": "رحيم", "derivation_level": 3})

# String aliases are also accepted
>>> api.do({"action": "search", "query": "كتب", "derivation_level": "root"})

派生语法 >word、>>word、>>>word 分别映射到层级 1、2、3，并可直接嵌入查询：

# Stem-level derivation in a query expression
>>> api.do({"action": "search", "query": ">رحيم"})

# Root-level: all words from root ملك
>>> api.do({"action": "search", "query": ">>>ملك"})

# Combined with field filters
>>> api.do({"action": "search", "query": ">>الله AND سورة:الإخلاص"})

词语搜索（unit="word"）

当 unit="word" 时，引擎会搜索词语级子文档，而不是诗节级父文档。每个词语子文档都包含完整的形态学标注——词性、词元、词干、词根、词型、性别、数、人物、语态、语气、派生层级等。

# Search all words matching "الله" at word level
>>> api.do({"action": "search", "query": "الله", "unit": "word"})

# Derivation levels also apply to word search:
# Level 1 — search word_stem (corpus-derived stem)
>>> api.do({"action": "search", "query": "رحيم", "unit": "word", "derivation_level": 1})

# Level 2 — search word_lemma (normalized lemma)
>>> api.do({"action": "search", "query": "رحيم", "unit": "word", "derivation_level": 2})

# Level 3 — search root (exact root value, e.g. "رحم")
>>> api.do({"action": "search", "query": "رحم", "unit": "word", "derivation_level": 3})

形态学筛选（search_by_word_linguistics）

使用 search_by_word_linguistics 操作，按任意组合的形态学属性筛选词语：

# Find all nouns from root قول
>>> api.do({
...     "action": "search_by_word_linguistics",
...     "root": "قول",
...     "type": "أسماء"       # Arabic POS category name
... })

# Find all active-voice past-tense verbs from root كتب
>>> api.do({
...     "action": "search_by_word_linguistics",
...     "root": "كتب",
...     "pos": "V",
...     "voice": "مبني للمعلوم",
...     "aspect": "فعل ماضي"
... })

# Find all proper nouns
>>> api.do({
...     "action": "search_by_word_linguistics",
...     "pos": "PN"
... })

可用的形态学筛选字段包括：pos、type、root、lemma、stem、pattern、gender、number、person、voice、mood、state、case、form、aspect、derivation、special、prefix、suffix、segments。

分面搜索可按字段汇总搜索结果：

>>> result = api.do({
...     "action": "search",
...     "query": u"الله",
...     "facets": "sura_id,juz,chapter"
... })
>>> print(result["search"]["facets"])

可用的分面字段：

• sura_id - 苏拉（章）编号（1-114）
• juz - 朱兹（部分）编号（1-30）
• hizb - 希兹布（分区）编号
• chapter - 主要主题／章节
• topic - 子主题
• sura_type - 麦加篇／麦地那篇分类

筛选结果

按字段值筛选搜索结果：

>>> api.do({
...     "action": "search",
...     "query": u"الله",
...     "filter": {"sura_id": "2"}  # Only from Sura Al-Baqarah
... })

搜索字段

字段搜索可用字段：

• سورة (sura) - 苏拉名称
• رقم_السورة (sura_id) - 苏拉编号
• رقم_الآية (aya_id) - 经文编号
• جزء (juz) - 朱兹编号
• حزب (hizb) - 希兹布编号
• صفحة (page) - 《古兰经》抄本中的页码
• سجدة (sajda) - 是否包含叩拜
• موضوع (subject) - 主题
• فصل (chapter) - 章节
• باب (subtopic) - 子主题
• نوع_السورة (sura_type) - 苏拉类型（麦加篇／麦地那篇）

词级字段（与 unit="word" 配合使用）：

• englishstate - 英语中的名词状态（例如 “Definite state”、“Indefinite state”）
• englishmood - 英语中的动词语气（例如 “Indicative mood”、“Subjunctive mood”、“Jussive mood”）

如需完整字段列表，请调用：

>>> api.do({"action": "show", "query": "fields"})

输出视图

不同视图提供不同详细程度的信息：

• minimal - 基本经文文本和标识符
• normal - 经文文本及必要元数据
• full - 所有可用信息
• statistic - 包含统计信息
• linguistic - 包含语言分析

示例：

>>> api.do({
...     "action": "search",
...     "query": u"الله",
...     "view": "full",
...     "word_info": True,
...     "aya_theme_info": True
... })

元数据访问

使用 “show” 操作获取各种元数据：

# Get list of available translations
>>> api.do({"action": "show", "query": "translations"})

# Get list of recitations
>>> api.do({"action": "show", "query": "recitations"})

# Get Sura information
>>> api.do({"action": "show", "query": "surates"})

# Get search fields
>>> api.do({"action": "show", "query": "fields"})

# Get default values
>>> api.do({"action": "show", "query": "defaults"})

注意： show 不再提供词元。使用 api.do({"action": "list_values", "field": "lemma"}) 按需检索。

添加新译本

你可以使用 index_translations() 将其他与 Zekr 兼容的 .trans.zip 译本文件添加到本地搜索索引中。这需要 alfanous_import 包（仓库中的 src/alfanous_import/ 目录已包含该包）。

import alfanous.api as alfanous

# Index all .trans.zip files found in a folder
count = alfanous.index_translations(source="/path/to/translations")
print(f"{count} translation(s) newly indexed")

该函数：

• 遍历 source 中的每个 *.trans.zip 文件
• 跳过已在索引中的译本（幂等，可安全重复调用）
• 返回新建索引的译本数量（0 表示没有新增内容）
• 自动更新 configs/translations.json，使新译本立即可通过 api.get_info("translations") 查看，并可使用 unit="translation" 进行搜索

完成索引后，搜索新译本：

# Search in a newly indexed translation
result = alfanous.search(u"الرحمن", unit="translation", flags={"translation": "en.newt"})

完整操作指南请参阅 examples/index_translations_example.py。

示例

examples/ 目录包含演示各种功能的示例脚本：

• facet_search_examples.py - 分面搜索和筛选示例

更多信息请参阅 examples/README.md。

MCP 服务

Alfanous 提供 MCP（模型上下文协议） 服务，让 AI 助手（Claude、Copilot 等）可以直接搜索和探索《古兰经》。完整参考文档请参阅 alfanous_mcp/README.md。

快速开始：

$ pip install alfanous3-mcp
$ python -m alfanous_mcp.mcp_server        # stdio – works with Claude Desktop

若要连接 Claude Desktop，请将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "alfanous": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "alfanous_mcp.mcp_server"],
      "tools": [
        "search_quran",
        "search_translations",
        "get_quran_info",
        "search_quran_by_themes",
        "search_quran_by_stats",
        "search_quran_by_position",
        "suggest_query",
        "correct_query",
        "search_by_word_linguistics",
        "list_field_values"
      ]
    }
  }
}

Web 界面

Alfanous 提供基于 FastAPI 的 Web 服务，以 RESTful 方式访问。有关以下内容，请参阅 alfanous_webapi/README.md：

• 安装和设置
• API 端点
• 请求／响应示例
• 交互式 API 文档（Swagger UI）

快速开始：

$ pip install alfanous3 fastapi uvicorn
$ cd src/
$ uvicorn alfanous_webapi.web_api:app --reload

然后访问 http://localhost:8000/docs 查看交互式文档。

贡献

欢迎贡献！以下内容请参阅 CONTRIBUTING.md：

• 设置开发环境
• 从源代码构建
• 运行测试
• 提交拉取请求
• 代码风格指南

快速设置开发环境：

# Clone the repository
$ git clone https://github.com/Alfanous-team/alfanous.git
$ cd alfanous

# Install dependencies
$ pip install pyparsing whoosh pystemmer pytest

# Build indexes (required for development)
$ make build

# Run tests
$ pytest -vv --rootdir=src/

支持

• GitHub Issues：https://github.com/Alfanous-team/alfanous/issues
• 邮件列表：[email protected]
• 网站：http://alfanous.org

许可证

Alfanous 使用 GNU Lesser General Public License v3 or later (LGPLv3+) 进行许可。

详情请参阅 LICENSE。

致谢

• 贡献者：请参阅 AUTHORS.md 和 THANKS.md

本项目处理神圣的宗教文本（《古兰经》）——请尊重相关数据和代码。

旧版

如果你要查找旧版 Alfanous 代码，可以在 legacy 分支中找到。