INSTALL_DEPENDENCIES.md

依赖库安装指南

📋 完整依赖列表

Wiki Dump上传功能需要的所有依赖库：

核心依赖（必需）

# XML Dump处理
mwxml                    # MediaWiki XML dump解析库
mwparserfromhell        # MediaWiki wikicode解析库

# Web框架
fastapi                 # 异步Web框架
uvicorn                 # ASGI服务器
python-multipart        # 文件上传支持

# 数据库
qdrant-client           # Qdrant向量数据库客户端

# 机器学习
torch                   # PyTorch（CPU版本）
transformers            # Hugging Face Transformers
pillow                  # 图像处理
numpy                   # 数值计算
scipy                   # 科学计算

# 网络和爬虫
requests                # HTTP请求库
beautifulsoup4          # HTML解析
lxml                    # XML/HTML解析
aiohttp                 # 异步HTTP客户端
fake-useragent          # User-Agent生成

# 其他工具
python-dotenv           # 环境变量管理
google-generativeai     # Google Gemini API
maturin                 # Rust构建工具

标准库（无需安装）

以下库是Python标准库，无需额外安装：

• os, sys, csv, argparse, re, typing
• collections, pathlib, datetime, time
• asyncio, io, uuid, tempfile
• bz2, gzip （压缩文件处理）

🚀 快速安装

方法1: 使用 requirements.txt（推荐）

# 安装所有依赖
pip install -r requirements.txt

方法2: 只安装Wiki Dump功能所需依赖

# 安装Wiki Dump处理所需的最小依赖
pip install mwxml mwparserfromhell fastapi uvicorn python-multipart qdrant-client python-dotenv

方法3: 使用虚拟环境（推荐）

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
# Linux/Mac:
source venv/bin/activate
# Windows:
# venv\Scripts\activate

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

🔍 验证安装

运行以下命令验证所有依赖是否正确安装：

python3 -c "
import sys
missing = []
modules = {
    'mwxml': 'XML Dump解析',
    'mwparserfromhell': 'Wikicode解析',
    'fastapi': 'Web框架',
    'uvicorn': 'Web服务器',
    'qdrant_client': '数据库客户端',
    'torch': 'PyTorch',
    'transformers': 'Transformers',
    'bs4': 'BeautifulSoup',
    'dotenv': '环境变量',
}

for module, desc in modules.items():
    try:
        __import__(module)
        print(f'✅ {module:20s} - {desc}')
    except ImportError:
        print(f'❌ {module:20s} - {desc} (缺失)')
        missing.append(module)

if missing:
    print(f'\n❌ 缺失 {len(missing)} 个依赖库')
    print('请运行: pip install -r requirements.txt')
    sys.exit(1)
else:
    print('\n✅ 所有依赖库已正确安装！')
"

📝 常见问题

问题1: mwxml 安装失败

错误信息: ERROR: Could not find a version that satisfies the requirement mwxml

解决方案:

# 确保pip是最新版本
pip install --upgrade pip

# 尝试从PyPI安装
pip install mwxml

# 如果还是失败，检查Python版本（需要Python 3.7+）
python3 --version

问题2: torch 安装慢或失败

解决方案:

# 使用CPU版本（更快）
pip install torch --index-url https://download.pytorch.org/whl/cpu

# 或者使用国内镜像
pip install torch -i https://pypi.tuna.tsinghua.edu.cn/simple

问题3: 依赖冲突

解决方案:

# 使用虚拟环境隔离依赖
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

🔧 Docker环境

如果使用Docker，依赖会在构建时自动安装：

docker build -t tum-search .
docker run -p 8000:8000 tum-search

📦 最小化安装

如果只需要Wiki Dump上传功能，最小依赖为：

pip install \
    mwxml \
    mwparserfromhell \
    fastapi \
    uvicorn \
    python-multipart \
    qdrant-client \
    python-dotenv

注意：这将无法使用搜索、图像处理等其他功能。

✅ 安装后检查

安装完成后，测试功能是否正常：

# 1. 检查模块导入
python3 -c "from xml_dump_processor import MediaWikiDumpProcessor; print('✅ XML Dump处理器可用')"

# 2. 检查Web服务器
python3 -c "from web_server import app; print('✅ Web服务器可用')"

# 3. 启动服务器测试
python3 web_server.py --mode user --port 8000

如果所有检查都通过，说明依赖安装成功！