common-skills

LlamaFarm 通用技能

common/ 包的最佳实践和代码审查清单——这是 LlamaFarm 所有服务共用的 Python 实用工具。

组件概览

属性	值
路径	common/
包	llamafarm-common
Python	3.10+
主要依赖项	huggingface_hub、hf-transfer

用途

common/ 包提供了多个 Python 服务需要保持一致的共享功能：

• 模型文件实用工具（GGUF 选择、量化解析）
• HuggingFace Hub 集成（列出、下载）
• 进程管理（PID 文件）

共享 Python 技能

此技能继承了共享 Python 技能中的所有模式：

主题	文件	相关内容
模式	../python-skills/patterns.md	数据类、类型提示、推导式
类型标注	../python-skills/typing.md	类型注解、现代语法
测试	../python-skills/testing.md	Pytest 夹具、模拟 HuggingFace API
错误	../python-skills/error-handling.md	自定义异常、日志记录
安全	../python-skills/security.md	路径验证、安全文件处理

框架专用清单

主题	文件	要点
HuggingFace	huggingface.md	Hub API、模型下载、缓存、身份验证

模块结构

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

公共 API

模型实用工具

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,
)

PID 文件管理

from llamafarm_common.pidfile import write_pid, get_pid_file

审查清单摘要

审查 common/ 中的代码时：

1. HuggingFace 集成（高优先级）

   • 妥善处理网络故障
   • 正确传递身份验证令牌
   • 适当启用高速传输

2. 模型选择（中优先级）

   • 保持量化偏好顺序
   • 匹配时不区分大小写
   • 首选项不可用时优雅回退

3. 测试（高优先级）

   • 模拟 HuggingFace API 调用
   • 测试中隔离网络
   • 覆盖边界情况（空列表、缺失文件）

4. 安全（中优先级）

   • 不在日志中暴露令牌
   • 安全处理文件路径
   • 保护环境变量

详细的 HuggingFace 专用清单请参阅 huggingface.md。