maque (麻雀)

Python toolkit for ML, CV, NLP and multimodal AI development

Features

• LLM Server - Local LLM inference with Transformers backend
• Model Quantization - Support auto-round, AWQ, GPTQ, BNB quantization methods
• Embedding Service - Text/multimodal embedding API server
• Vector Retrievers - Chroma / Milvus / Lance 后端，统一 API（upsert_batch / search / aiter_rows / describe）
• Clustering Pipeline - UMAP + HDBSCAN for vector clustering and visualization
• Rich CLI - Modular command groups for various tasks

Installation

# Basic installation
pip install maque

# With specific feature sets
pip install maque[torch,nlp,cv]                       # ML/NLP/CV features
pip install maque[clustering,embedding,retriever]     # 向量检索 + 聚类（Chroma + Milvus）
pip install maque[lancedb]                            # LanceRetriever（含 pylance）
pip install maque[quant]                              # Model quantization support
pip install maque[dev,test]                           # Development setup

# From source
pip install -e .
pip install -e .[dev,test]

CLI Usage

Commands are organized into groups: maque <group> <command>. Short alias mq is also available.

Config Management

maque config show                 # Show current configuration
maque config edit                 # Open config in editor
maque config init                 # Initialize config file

LLM Server (本地推理)

# Start LLM inference server (Transformers backend)
maque llm serve Qwen/Qwen2.5-7B-Instruct --port=8000

# With LoRA adapters
maque llm serve Qwen/Qwen2.5-7B-Instruct --lora_modules lora1=/path/to/lora1

# AWQ quantized model (requires: pip install maque[quant])
maque llm serve Qwen2.5-VL-3B-Instruct-AWQ

Embedding Service

# Start embedding API server
maque embedding serve --model=BAAI/bge-m3 --port=8001

# Test embedding endpoint
maque embedding test --text="Hello world"

Data Processing

# Interactive table viewer (Streamlit)
maque data table-viewer data.csv --port=8501

# Convert between formats
maque data convert input.json output.csv

System Utilities

# Kill processes on ports
maque system kill 8000 8001

# Pack directory
maque system pack ./folder

# Split large file
maque system split large_file.dat --chunk_size=1GB

Claude Code Skill

# Install maque skill to Claude Code
maque install-skill

# Check installation status
maque skill-status

# Uninstall skill
maque uninstall-skill

After installation, use /maque in Claude Code to access maque documentation.

Git Helpers

# GitHub 镜像代理（国内加速）
maque git mirror-set                      # 设置全局镜像（默认 ghproxy）
maque git mirror-set --mirror=ghproxy-cdn # 使用 CDN 镜像
maque git mirror-status                   # 查看当前镜像配置
maque git mirror-unset                    # 移除镜像，恢复直连

# 设置后，原生 git 命令自动走镜像
git clone https://github.com/user/repo    # 自动使用镜像加速

# 可用镜像列表
maque git mirrors

# 单次使用镜像克隆（不修改全局配置）
maque git clone-mirror https://github.com/user/repo ./repo

Python API

IO Utilities

from maque import yaml_load, yaml_dump, json_load, json_dump, jsonl_load, jsonl_dump

# Load/save YAML
config = yaml_load("config.yaml")
yaml_dump(data, "output.yaml")

# Load/save JSONL
records = jsonl_load("data.jsonl")
jsonl_dump(records, "output.jsonl")

Embedding & Retrieval

from maque.embedding import TextEmbedding
from maque.retriever import ChromaRetriever, Document

# Initialize
embedding = TextEmbedding(base_url="http://localhost:8001/v1", model="bge-m3")
retriever = ChromaRetriever(
    embedding,
    persist_dir="./chroma_db",
    collection_name="my_data"
)

# Insert documents
documents = [Document(id="1", content="text...", metadata={"source": "file1"})]
retriever.upsert_batch(documents, batch_size=32, skip_existing=True)

# Search
results = retriever.search("query text", top_k=10)

Milvus / Lance 后端 API 一致，并额外提供流式扫描与跨后端统一元信息：

from maque.retriever import MilvusRetriever, LanceRetriever

# Milvus（生产级，AsyncMilvusClient）
mv = MilvusRetriever(embedding, uri="http://localhost:19530", collection_name="docs")

# Lance（本地零运维，列式过滤）
lz = LanceRetriever(
    embedding, persist_dir="./lance_db", table_name="docs",
    extra_fields={"category": str, "price": float},  # 提升为独立列，可 SQL 过滤
)
results = lz.search("query", top_k=5, where="category = 'tech'")

# 流式扫描（不爆内存，适合 100k+ 全量或 filter 子集）
for row in lz.iter_rows(expr="category = 'tech'", batch_size=1000):
    ...

# 跨后端统一元信息
desc = lz.describe()
# {"schema": [...], "dim": 768, "count": 12345, "indexes": [...], "primary_key": "id"}

# async 接口（FastAPI / asyncio 场景不阻塞事件循环）
import asyncio
async def main():
    async for row in mv.aiter_rows(expr='feedback == "bad"'):
        ...
    desc = await lz.adescribe()
asyncio.run(main())

Clustering Pipeline

from maque.clustering import ClusterAnalyzer

analyzer = ClusterAnalyzer(algorithm="hdbscan", min_cluster_size=15)

# Analyze from ChromaDB
result = analyzer.analyze_chroma(
    persist_dir="./chroma_db",
    collection_name="my_data",
    output_dir="./results",
    sample_size=10000,
    visualize=True
)

# Access results
print(f"Found {result.n_clusters} clusters")
print(result.labels)
print(result.cluster_stats)

Performance Measurement

from maque import MeasureTime

with MeasureTime("model inference", gpu=True):
    output = model(input)
# Prints: model inference took 0.123s (GPU: 0.089s)

Configuration

maque uses hierarchical configuration (highest priority first):

1. ./maque_config.yaml (current directory)
2. Project root config
3. ~/.maque/config.yaml (user config)

Example configuration:

embedding:
  model: BAAI/bge-m3
  base_url: http://localhost:8001/v1

llm:
  default_port: 8000

Initialize config:

maque config init

Development

# Install development dependencies
pip install -e .[dev,test]

# Run tests
pytest
pytest -m "not slow"  # Skip slow tests

# Format code
black .
isort .

License

MIT License - see LICENSE for details.