# py-cpuinfo 详细使用文档

**py-cpuinfo** 是一个轻量级的 Python 库，用于**跨平台获取 CPU 信息**，无需安装系统级依赖，适用于 Linux / Windows / macOS / BSD 等系统。它常用于性能分析、环境检测、硬件审计、自动化运维等场景。

---

## 一、简介

- **项目名称**：py-cpuinfo  
- **GitHub**：https://github.com/workhorsy/py-cpuinfo  
- **主要功能**：  
  - 获取 CPU 型号、厂商、架构  
  - 获取 CPU 核心数（物理 / 逻辑）  
  - 获取 CPU 频率、缓存大小  
  - 获取 CPU 支持的指令集（如 AVX、SSE、AES）  
- **特点**：  
  - 纯 Python 实现  
  - 无外部依赖  
  - 跨平台兼容性好  

---

## 二、安装方法

### 1. 使用 pip 安装（推荐）

```bash
pip install py-cpuinfo
```

### 2. 验证安装是否成功

```bash
python -c "import cpuinfo; print(cpuinfo.get_cpu_info()['brand_raw'])"
```

如果输出了 CPU 型号名称，说明安装成功。

---

## 三、快速入门示例

```python
from cpuinfo import get_cpu_info

info = get_cpu_info()
print(info)
```

该代码会返回一个包含 CPU 所有信息的字典对象。

---

## 四、核心 API 说明

### 1. `cpuinfo.get_cpu_info()`

**功能**：获取完整的 CPU 信息  
**返回值类型**：`dict`

```python
from cpuinfo import get_cpu_info

cpu = get_cpu_info()
```

---

## 五、常用字段详解

以下是 `get_cpu_info()` 返回字典中**最常用、最重要的字段说明**。不同平台字段可能略有差异，但核心字段基本一致。

### 1. 基础信息

| 字段名 | 含义 | 示例 |
|------|------|------|
| `brand_raw` | CPU 原始品牌字符串 | `"Intel(R) Core(TM) i7-9700K CPU @ 3.60GHz"` |
| `vendor_id_raw` | CPU 厂商 ID | `"GenuineIntel"` |
| `arch` | 架构 | `"X86_64"` |
| `family` | CPU 家族编号 | `6` |
| `model` | 型号编号 | `158` |
| `stepping` | 步进 | `13` |

---

### 2. 核心与线程信息

| 字段名 | 含义 | 示例 |
|------|------|------|
| `count` | 逻辑 CPU 数量 | `8` |
| `cores` | 物理核心数 | `4` |
| `threads_per_core` | 每核线程数 | `2` |

> ✅ 常见关系：  
> `逻辑 CPU 数 = 物理核心数 × threads_per_core`

---

### 3. 频率信息（单位：MHz）

| 字段名 | 含义 | 示例 |
|------|------|------|
| `hz_advertised_friendly` | 标称主频 | `"3.6000 GHz"` |
| `hz_actual_friendly` | 当前实际主频 | `"4.9000 GHz"` |
| `hz_advertised` | 标称主频（数值） | `[3600000000, 0]` |
| `hz_actual` | 实际主频（数值） | `[4900000000, 0]` |

---

### 4. 缓存信息（单位：字节）

| 字段名 | 含义 | 示例 |
|------|------|------|
| `l1_data_cache_size` | L1 数据缓存 | `32768` |
| `l1_instruction_cache_size` | L1 指令缓存 | `32768` |
| `l2_cache_size` | L2 缓存 | `262144` |
| `l3_cache_size` | L3 缓存 | `8388608` |

---

### 5. 指令集支持

| 字段名 | 含义 |
|------|------|
| `flags` | CPU 支持的所有指令集标志（列表） |

示例：

```python
cpu['flags']
# ['avx', 'avx2', 'sse', 'sse2', 'sse3', 'ssse3', 'aes', ...]
```

可用于判断 CPU 是否支持某些优化指令，如：

```python
if 'avx2' in cpu['flags']:
    print("CPU 支持 AVX2")
```

---

## 六、常见使用示例

### 1. 获取 CPU 型号

```python
from cpuinfo import get_cpu_info

cpu = get_cpu_info()
print(cpu['brand_raw'])
```

---

### 2. 判断 CPU 厂商

```python
vendor = cpu['vendor_id_raw']
if vendor == "GenuineIntel":
    print("Intel CPU")
elif vendor == "AuthenticAMD":
    print("AMD CPU")
```

---

### 3. 判断 CPU 架构

```python
arch = cpu['arch']
print(arch)  # X86_32 / X86_64 / ARM_7 / ARM_8
```

---

### 4. 判断是否为服务器 CPU（辅助判断）

```python
if cpu['cores'] >= 16:
    print("可能是服务器 CPU")
```

---

### 5. 判断是否支持 AES / AVX2

```python
if 'aes' in cpu['flags'] and 'avx2' in cpu['flags']:
    print("适合加密和并行计算")
```

---

### 6. 获取 CPU 缓存大小（MB）

```python
l3_mb = cpu['l3_cache_size'] / (1024 * 1024)
print(f"L3 Cache: {l3_mb:.1f} MB")
```

---

## 七、命令行用法（CLI）

py-cpuinfo 也提供了简单的命令行工具。

### 1. 查看所有 CPU 信息

```bash
python -m cpuinfo
```

### 2. 只查看 CPU 型号

```bash
python -m cpuinfo | grep brand_raw
```

---

## 八、平台兼容性说明

| 操作系统 | 支持情况 |
|--------|--------|
| Linux | ✅ 完全支持 |
| Windows | ✅ 完全支持 |
| macOS | ✅ 支持 |
| FreeBSD / OpenBSD | ✅ 基本支持 |
| ARM / x86 | ✅ 均支持 |

⚠️ 注意：
- 部分字段在某些平台可能为空或不完整  
- ARM 架构下字段数量通常少于 x86

---

## 九、常见问题（FAQ）

### Q1：为什么 `hz_actual` 为 0？
A：在某些虚拟化环境或受限系统中，无法读取实时频率，此时通常回退为标称频率。

### Q2：为什么 `cores` 和 `count` 一样？
A：说明 CPU 不支持超线程（Hyper-Threading）。

### Q3：能否用于生产环境？
A：可以。py-cpuinfo 是只读、无副作用的库，适合生产环境使用。

---

## 十、最佳实践建议

- ✅ 只读取所需字段，避免一次性解析全部信息  
- ✅ 在程序启动时缓存结果，避免频繁调用  
- ✅ 结合 `platform`、`os` 模块一起使用，增强环境判断能力  

示例：

```python
import platform
from cpuinfo import get_cpu_info

print(platform.system(), platform.release())
print(get_cpu_info()['brand_raw'])
```

---

## 十一、总结

py-cpuinfo 是一个**简单、可靠、跨平台**的 CPU 信息获取工具，非常适合用于：

- 性能调优  
- 环境检测  
- 软件兼容性判断  
- 自动化运维与硬件审计