Back to Details

common-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Common Skills for LlamaFarm

LlamaFarm的Common工具包实践指南

Best practices and code review checklists for the 
common/
package - shared Python utilities used across all LlamaFarm services.
本内容为
common/
包的最佳实践与代码审查清单，该包是LlamaFarm所有服务共用的Python工具集。

Component Overview

组件概述

AttributeValue
Path
common/
Package
llamafarm-common
Python3.10+
Key Dependencieshuggingface_hub, hf-transfer
属性值
路径
common/
包名
llamafarm-common
Python版本3.10+
核心依赖huggingface_hub, hf-transfer

Purpose

用途

The 
common/
package provides shared functionality that needs to be consistent across multiple Python services:
  • Model file utilities (GGUF selection, quantization parsing)
  • HuggingFace Hub integration (listing, downloading)
  • Process management (PID files)
common/
包提供在多个Python服务中需保持一致的共享功能：
  • 模型文件工具（GGUF选择、量化解析）
  • HuggingFace Hub集成（列表展示、下载）
  • 进程管理（PID文件）

Shared Python Skills

通用Python实践要点

This skill inherits all patterns from the shared Python skills:
TopicFileRelevance
Patterns../python-skills/patterns.mdDataclasses, type hints, comprehensions
Typing../python-skills/typing.mdType annotations, modern syntax
Testing../python-skills/testing.mdPytest fixtures, mocking HuggingFace APIs
Errors../python-skills/error-handling.mdCustom exceptions, logging
Security../python-skills/security.mdPath validation, safe file handling
本工具包遵循所有通用Python实践模式：
主题文件相关内容
设计模式../python-skills/patterns.md数据类、类型提示、推导式
类型标注../python-skills/typing.md类型注解、现代语法
测试../python-skills/testing.mdPytest夹具、HuggingFace API模拟
错误处理../python-skills/error-handling.md自定义异常、日志记录
安全../python-skills/security.md路径验证、安全文件处理

Framework-Specific Checklists

框架专属审查清单

TopicFileKey Points
HuggingFacehuggingface.mdHub API, model download, caching, authentication
主题文件核心要点
HuggingFacehuggingface.mdHub API、模型下载、缓存、身份验证

Module Structure

模块结构

common/
├── pyproject.toml           # UV-managed dependencies
├── llamafarm_common/
│   ├── __init__.py          # Public API exports
│   ├── model_utils.py       # GGUF file utilities
│   └── pidfile.py           # PID file management
└── tests/
    └── test_model_utils.py  # Unit tests with mocking
common/
├── pyproject.toml           # UV管理的依赖
├── llamafarm_common/
│   ├── __init__.py          # 公开API导出
│   ├── model_utils.py       # GGUF文件工具
│   └── pidfile.py           # PID文件管理
└── tests/
    └── test_model_utils.py  # 带模拟的单元测试

Public API

公开API

Model Utilities

模型工具

python
from llamafarm_common import (
    # Parse model:quantization syntax
    parse_model_with_quantization,
    # Extract quantization from filename
    parse_quantization_from_filename,
    # Select best GGUF file from list
    select_gguf_file,
    select_gguf_file_with_logging,
    # List GGUF files in HF repo
    list_gguf_files,
    # Download and get path to GGUF file
    get_gguf_file_path,
    # Default quantization preference order
    GGUF_QUANTIZATION_PREFERENCE_ORDER,
)
python
from llamafarm_common import (
    # 解析model:quantization语法
    parse_model_with_quantization,
    # 从文件名提取量化信息
    parse_quantization_from_filename,
    # 从列表中选择最优GGUF文件
    select_gguf_file,
    select_gguf_file_with_logging,
    # 列出HF仓库中的GGUF文件
    list_gguf_files,
    # 下载并获取GGUF文件路径
    get_gguf_file_path,
    # 默认量化偏好顺序
    GGUF_QUANTIZATION_PREFERENCE_ORDER,
)

PID File Management

PID文件管理

python
from llamafarm_common.pidfile import write_pid, get_pid_file
python
from llamafarm_common.pidfile import write_pid, get_pid_file

Review Checklist Summary

审查清单摘要

When reviewing code in 
common/
:
  1. HuggingFace Integration (High priority)
    • Proper error handling for network failures
    • Authentication token passed correctly
    • High-speed transfer enabled appropriately
  2. Model Selection (Medium priority)
    • Quantization preference order maintained
    • Case-insensitive matching
    • Graceful fallback when preferred not available
  3. Testing (High priority)
    • HuggingFace API calls mocked
    • Network isolation in tests
    • Edge cases covered (empty lists, missing files)
  4. Security (Medium priority)
    • No token exposure in logs
    • Safe file path handling
    • Environment variable protection
See huggingface.md for detailed HuggingFace-specific checklists.
审查
common/
中的代码时，需关注以下几点：
  1. HuggingFace集成（高优先级）
    • 为网络故障设置适当的错误处理
    • 正确传递身份验证令牌
    • 合理启用高速传输
  2. 模型选择（中优先级）
    • 维持量化偏好顺序
    • 支持大小写不敏感匹配
    • 当偏好模型不可用时优雅降级
  3. 测试（高优先级）
    • 模拟HuggingFace API调用
    • 测试中隔离网络依赖
    • 覆盖边缘场景（空列表、文件缺失）
  4. 安全（中优先级）
    • 日志中不暴露令牌信息
    • 安全处理文件路径
    • 保护环境变量
详细的HuggingFace专属审查清单请参考huggingface.md。