maque 0.2.1__py3-none-any.whl

maque/cli/groups/doctor.py

@@ -0,0 +1,259 @@
+"""环境检查和诊断命令组"""
+import os
+import sys
+import subprocess
+import importlib
+from pathlib import Path
+from rich.console import Console
+from rich.table import Table
+from rich import print
+
+
+class DoctorGroup:
+    """环境检查和诊断命令组"""
+    
+    def __init__(self, cli_instance):
+        self.cli = cli_instance
+        self.console = Console()
+    
+    def check(self, verbose: bool = False):
+        """检查环境和依赖"""
+        print("[bold blue]Sparrow 环境诊断[/bold blue]\n")
+        
+        issues = []
+        
+        # 检查Python版本
+        issues.extend(self._check_python_version(verbose))
+        
+        # 检查核心依赖
+        issues.extend(self._check_core_dependencies(verbose))
+        
+        # 检查可选依赖
+        issues.extend(self._check_optional_dependencies(verbose))
+        
+        # 检查配置文件
+        issues.extend(self._check_config_files(verbose))
+        
+        # 检查服务连接
+        issues.extend(self._check_services(verbose))
+        
+        # 汇总结果
+        print("\n" + "="*50)
+        if issues:
+            print(f"[yellow]发现 {len(issues)} 个问题:[/yellow]")
+            for i, issue in enumerate(issues, 1):
+                print(f"{i}. [yellow]{issue}[/yellow]")
+            
+            print(f"\n[bold cyan]建议运行 'maque doctor fix' 来自动修复部分问题[/bold cyan]")
+        else:
+            print("[green]✓ 环境检查完成，未发现问题[/green]")
+        
+        return len(issues) == 0
+    
+    def _check_python_version(self, verbose):
+        """检查Python版本"""
+        issues = []
+        python_version = sys.version_info
+        
+        if verbose or python_version < (3, 8):
+            print(f"Python 版本: {python_version.major}.{python_version.minor}.{python_version.micro}")
+        
+        if python_version < (3, 8):
+            issues.append("Python版本过低，建议使用Python 3.8+")
+        elif verbose:
+            print("[green]✓[/green] Python版本符合要求")
+        
+        return issues
+    
+    def _check_core_dependencies(self, verbose):
+        """检查核心依赖"""
+        core_deps = [
+            'fire',
+            'rich', 
+            'pyyaml',
+            'requests',
+            'pathlib'  # 标准库，但检查兼容性
+        ]
+        
+        issues = []
+        
+        if verbose:
+            print("\n[bold]核心依赖检查:[/bold]")
+        
+        for dep in core_deps:
+            try:
+                importlib.import_module(dep.replace('-', '_'))
+                if verbose:
+                    print(f"[green]✓[/green] {dep}")
+            except ImportError:
+                issues.append(f"缺少核心依赖: {dep}")
+                if verbose:
+                    print(f"[red]✗[/red] {dep} - 未安装")
+        
+        return issues
+    
+    def _check_optional_dependencies(self, verbose):
+        """检查可选依赖"""
+        optional_deps = {
+            'cv2': 'opencv-python (视频处理)',
+            'torch': 'torch (深度学习)',
+            'pandas': 'pandas (数据处理)',
+            'numpy': 'numpy (数值计算)',
+            'PIL': 'pillow (图像处理)',
+            'httpx': 'httpx (异步HTTP客户端)',
+            'uvicorn': 'uvicorn (Web服务器)'
+        }
+        
+        issues = []
+        missing_optional = []
+        
+        if verbose:
+            print("\n[bold]可选依赖检查:[/bold]")
+        
+        for dep, description in optional_deps.items():
+            try:
+                importlib.import_module(dep)
+                if verbose:
+                    print(f"[green]✓[/green] {dep} - {description}")
+            except ImportError:
+                missing_optional.append(f"{dep} ({description})")
+                if verbose:
+                    print(f"[yellow]○[/yellow] {dep} - {description} (未安装)")
+        
+        if missing_optional and not verbose:
+            # 非详细模式下只提示有多少个可选依赖未安装
+            print(f"[yellow]提示: {len(missing_optional)} 个可选依赖未安装，某些功能可能不可用[/yellow]")
+        
+        return issues
+    
+    def _check_config_files(self, verbose):
+        """检查配置文件"""
+        issues = []
+        
+        if verbose:
+            print("\n[bold]配置文件检查:[/bold]")
+        
+        config_paths = self.cli._get_config_search_paths()
+        found_config = False
+        
+        for path in config_paths:
+            if path.exists():
+                found_config = True
+                try:
+                    # 验证配置文件
+                    config = self.cli._load_maque_config()
+                    if verbose:
+                        print(f"[green]✓[/green] 配置文件: {path}")
+                    break
+                except Exception as e:
+                    issues.append(f"配置文件错误: {path} - {e}")
+                    if verbose:
+                        print(f"[red]✗[/red] 配置文件: {path} - 错误: {e}")
+        
+        if not found_config:
+            if verbose:
+                print("[yellow]○[/yellow] 未找到配置文件，将使用默认配置")
+        
+        return issues
+    
+    def _check_services(self, verbose):
+        """检查服务连接"""
+        issues = []
+        
+        if verbose:
+            print("\n[bold]服务连接检查:[/bold]")
+        
+        # 检查MLLM服务
+        mllm_config = self.cli.maque_config.get('mllm', {})
+        base_url = mllm_config.get('base_url')
+        
+        if base_url:
+            try:
+                import requests
+                # 简单的连接测试
+                response = requests.get(f"{base_url.rstrip('/')}/models", timeout=5)
+                if response.status_code == 200:
+                    if verbose:
+                        print(f"[green]✓[/green] MLLM服务: {base_url}")
+                else:
+                    issues.append(f"MLLM服务响应异常: {base_url} (状态码: {response.status_code})")
+            except requests.RequestException as e:
+                issues.append(f"无法连接MLLM服务: {base_url}")
+                if verbose:
+                    print(f"[red]✗[/red] MLLM服务: {base_url} - {e}")
+            except ImportError:
+                pass  # requests未安装，已在依赖检查中处理
+
+        return issues
+    
+    def fix(self, auto: bool = False):
+        """自动修复常见问题
+        
+        Args:
+            auto: 自动修复而不询问
+        """
+        print("[bold blue]自动修复工具[/bold blue]\n")
+        
+        fixes_applied = 0
+        
+        # 检查并创建配置文件
+        config_paths = self.cli._get_config_search_paths()
+        has_config = any(p.exists() for p in config_paths)
+        
+        if not has_config:
+            if auto or self._confirm("创建默认配置文件？"):
+                self.cli.init_config()
+                print("[green]✓[/green] 已创建默认配置文件")
+                fixes_applied += 1
+        
+        # 可以添加更多自动修复逻辑...
+        
+        if fixes_applied > 0:
+            print(f"\n[green]已应用 {fixes_applied} 个修复[/green]")
+        else:
+            print("[yellow]未发现可自动修复的问题[/yellow]")
+    
+    def _confirm(self, message):
+        """确认对话"""
+        response = input(f"{message} (y/N): ")
+        return response.lower() == 'y'
+    
+    def version(self, full: bool = False):
+        """显示版本信息
+        
+        Args:
+            full: 显示详细版本信息
+        """
+        from maque import __version__
+        
+        if not full:
+            print(f"maque {__version__}")
+            return
+        
+        # 详细版本信息
+        print(f"[bold blue]Sparrow v{__version__}[/bold blue]\n")
+        
+        # Python信息
+        print(f"Python: {sys.version}")
+        print(f"平台: {sys.platform}")
+        
+        # 安装位置
+        maque_path = Path(__file__).parent.parent.parent
+        print(f"安装路径: {maque_path}")
+        
+        # 依赖版本
+        deps_info = []
+        key_deps = ['fire', 'rich', 'requests', 'pyyaml']
+        
+        for dep in key_deps:
+            try:
+                mod = importlib.import_module(dep)
+                version = getattr(mod, '__version__', 'unknown')
+                deps_info.append(f"{dep}: {version}")
+            except ImportError:
+                deps_info.append(f"{dep}: 未安装")
+        
+        if deps_info:
+            print(f"\n依赖版本:")
+            for info in deps_info:
+                print(f"  {info}")

maque/cli/groups/embedding.py

@@ -0,0 +1,222 @@
+"""Embedding 服务命令组"""
+from typing import List, Optional
+from rich import print
+from rich.console import Console
+
+
+class EmbeddingGroup:
+    """Embedding 服务命令组
+
+    提供 embedding 模型服务的启动、管理功能，
+    支持 jina-embeddings-v3 等模型的 task 类型。
+    """
+
+    def __init__(self, cli_instance):
+        self.cli = cli_instance
+        self.console = Console()
+
+    def serve(
+        self,
+        model: str = "jinaai/jina-embeddings-v3",
+        host: str = "0.0.0.0",
+        port: int = 8000,
+        device: str = None,
+        workers: int = 1,
+        local_dir: str = None,
+        dtype: str = None,
+        attn: str = None,
+    ):
+        """启动 Embedding API 服务
+
+        启动兼容 OpenAI/vLLM 的 Embedding API 服务，
+        支持 jina-embeddings-v3 的 task 类型扩展。
+
+        Args:
+            model: 模型名称或路径，默认 jinaai/jina-embeddings-v3
+            host: 监听地址，默认 0.0.0.0
+            port: 监听端口，默认 8000
+            device: 设备类型 (cuda/cpu)，默认自动检测
+            workers: worker 数量，默认 1
+            local_dir: 本地模型目录
+            dtype: 数据类型 (float16/bfloat16/float32)，默认自动选择
+            attn: 注意力实现 (eager/sdpa/flash_attention_2)，默认自动选择
+
+        Examples:
+            maque embedding serve
+            maque embedding serve --model=BAAI/bge-m3 --port=8001
+            maque embedding serve --dtype=float32 --attn=eager
+        """
+        try:
+            from maque.embedding.server import create_server
+        except ImportError as e:
+            print(f"[red]无法导入 embedding 服务模块: {e}[/red]")
+            print("请确保已安装依赖: pip install sentence-transformers fastapi uvicorn")
+            return
+
+        print(f"[bold blue]启动 Embedding 服务[/bold blue]")
+        print(f"  模型: [cyan]{model}[/cyan]")
+        print(f"  地址: [green]http://{host}:{port}[/green]")
+        print(f"  设备: [yellow]{device or 'auto'}[/yellow]")
+        print(f"  精度: [yellow]{dtype or 'auto'}[/yellow]")
+        print(f"  注意力: [yellow]{attn or 'auto'}[/yellow]")
+        if local_dir:
+            print(f"  本地目录: [magenta]{local_dir}[/magenta]")
+        print()
+
+        # 处理多模型
+        models = [m.strip() for m in model.split(",")] if "," in model else [model]
+
+        server = create_server(
+            models=models,
+            device=device,
+            local_dir=local_dir,
+            dtype=dtype,
+            attn=attn,
+        )
+        server.run(host=host, port=port, workers=workers)
+
+    def test(
+        self,
+        url: str = "http://localhost:8000",
+        model: str = "jinaai/jina-embeddings-v3",
+        text: str = "Hello, world!",
+        task: str = None,
+    ):
+        """测试 Embedding 服务
+
+        Args:
+            url: 服务 URL
+            model: 模型名称
+            text: 测试文本
+            task: 任务类型 (text-matching/retrieval.query/retrieval.passage/classification/separation)
+
+        Examples:
+            maque embedding test
+            maque embedding test --task=retrieval.query
+            maque embedding test --url=http://localhost:8000
+        """
+        import requests
+        import json
+
+        endpoint = f"{url.rstrip('/')}/v1/embeddings"
+
+        payload = {
+            "model": model,
+            "input": text,
+        }
+        if task:
+            payload["task"] = task
+
+        print(f"[blue]测试 Embedding 服务[/blue]")
+        print(f"  URL: {endpoint}")
+        print(f"  模型: {model}")
+        print(f"  文本: {text[:50]}{'...' if len(text) > 50 else ''}")
+        if task:
+            print(f"  Task: {task}")
+        print()
+
+        try:
+            response = requests.post(
+                endpoint,
+                json=payload,
+                headers={"Content-Type": "application/json"},
+                timeout=60,
+            )
+            response.raise_for_status()
+            data = response.json()
+
+            if "data" in data and len(data["data"]) > 0:
+                embedding = data["data"][0]["embedding"]
+                print(f"[green]成功![/green]")
+                print(f"  向量维度: {len(embedding)}")
+                print(f"  向量前5维: {embedding[:5]}")
+                print(f"  Token 使用: {data.get('usage', {})}")
+            else:
+                print(f"[yellow]响应异常: {data}[/yellow]")
+
+        except requests.exceptions.ConnectionError:
+            print(f"[red]无法连接到服务: {endpoint}[/red]")
+            print("请确保服务已启动")
+        except Exception as e:
+            print(f"[red]测试失败: {e}[/red]")
+
+    def tasks(self):
+        """显示支持的 task 类型
+
+        显示 jina-embeddings-v3 支持的所有 task 类型及其用途。
+        """
+        from rich.table import Table
+
+        print("[bold blue]jina-embeddings-v3 支持的 Task 类型[/bold blue]\n")
+
+        table = Table(show_header=True, header_style="bold magenta")
+        table.add_column("Task", style="cyan")
+        table.add_column("用途", style="green")
+        table.add_column("适用场景", style="yellow")
+
+        tasks = [
+            ("text-matching", "语义相似度匹配", "对称检索、句子相似度计算"),
+            ("retrieval.query", "检索查询编码", "非对称检索的查询端"),
+            ("retrieval.passage", "检索文档编码", "非对称检索的文档/段落端"),
+            ("classification", "文本分类", "分类任务的特征提取"),
+            ("separation", "聚类/重排", "聚类分析、重排序任务"),
+        ]
+
+        for task, desc, usage in tasks:
+            table.add_row(task, desc, usage)
+
+        self.console.print(table)
+
+        print("\n[dim]使用示例:[/dim]")
+        print('  curl -X POST http://localhost:8000/v1/embeddings \\')
+        print('    -H "Content-Type: application/json" \\')
+        print('    -d \'{"model": "jinaai/jina-embeddings-v3", "input": "text", "task": "retrieval.query"}\'')
+
+    def client(
+        self,
+        url: str = "http://localhost:8000",
+        model: str = "jinaai/jina-embeddings-v3",
+    ):
+        """创建 Embedding 客户端 (交互模式)
+
+        Args:
+            url: 服务 URL
+            model: 模型名称
+
+        Examples:
+            maque embedding client
+            maque embedding client --url=http://localhost:8000
+        """
+        from maque.embedding import TextEmbedding
+
+        print("[bold blue]Embedding 客户端 (交互模式)[/bold blue]")
+        print(f"  URL: {url}")
+        print(f"  模型: {model}")
+        print("\n输入文本进行编码，输入 'quit' 退出")
+        print("可选: 输入 'task:<type>' 切换任务类型\n")
+
+        client = TextEmbedding(base_url=url, model=model)
+        current_task = None
+
+        while True:
+            try:
+                text = input(f"[{current_task or 'default'}] > ").strip()
+
+                if not text:
+                    continue
+                if text.lower() == "quit":
+                    break
+                if text.startswith("task:"):
+                    current_task = text[5:].strip() or None
+                    print(f"  切换到 task: {current_task or 'default'}")
+                    continue
+
+                embeddings = client.embed(text, task=current_task)
+                print(f"  维度: {len(embeddings[0])}, 前5维: {embeddings[0][:5]}")
+
+            except KeyboardInterrupt:
+                break
+            except Exception as e:
+                print(f"  [red]错误: {e}[/red]")
+
+        print("\n[yellow]已退出[/yellow]")

maque/cli/groups/git.py

@@ -0,0 +1,29 @@
+"""Git 命令组 - 代理到 Dulwich CLI
+
+直接调用 dulwich CLI，支持所有 git 命令。
+注意：实际的 git 命令在 __main__.py 中直接处理，绕过 fire。
+
+Usage:
+    spr git <command> [args...]
+
+Examples:
+    spr git status
+    spr git add .
+    spr git commit -m "message"
+    spr git log
+    spr git rebase main
+    spr git stash push
+    spr git cherry-pick <commit>
+    spr git config -l
+"""
+
+
+class GitGroup:
+    """Git 命令组 - 代理到 Dulwich CLI
+
+    注意：此类仅作为占位符，实际的 git 命令处理在 __main__.py 中，
+    直接调用 dulwich CLI 以避免 fire 参数解析问题。
+    """
+
+    def __init__(self, cli_instance):
+        self.cli = cli_instance