Files
buryan-infra/ops/work/DATASHEET-FORMAT.md

141 lines
7.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Формат даташита: спроектирован по реальным файлам
Дата: 06.11.2026. Основано на **реальном разборе** даташитов Yealink из Nextcloud
(`Work/Datasheet/Yealink`, 187 PDF в 209).
---
## 1. Что реально лежит (факты)
| Вендор | PDF | Где |
|---|---|---|
| **Yealink** | **187** | `Work/Datasheet/Yealink/<модель>/*.pdf` |
| Hitrolink | ~15 | `Work/Datasheet/Hitrolink` |
| Poly | ~7 | `Work/Datasheet/Poly` |
**Структура папок Yealink:** по моделям — `ME 500`, `ME 500 PRO`, `Mspeaker Pro`,
`VCH51 Pro Package`, `Meeting Board`, `UVC86`, `UC` (документация, не даташиты).
**Важно:** в папках лежат **не только даташиты**: Quick Start Guide, Product Introduction,
Installation and Connection. Из 187 — даташитов примерно **30–40**, остальное — документация.
Это надо разделять по имени файла: `*Datasheet*.pdf` → даташит, остальное → `docs`.
---
## 2. Реальная структура даташита (по MeetingEye 500)
Текст извлекается `pdftotext -layout`. Структура — таблица «Параметр → Описание»:
```
Specification
Parameter Description
Chips and Systems • CPU: 4-core 2.6G + 4-core 2G
• AI Computing Power: 4T
• Operating System: Android 11
Camera • Camera: Optional UVC84/UV85/UVC86 (до 3)
• Third-party cameras: support
Audio Device • Microphone: Optional VCM35/VCM38/CP50/CPE40
• Speaker: Optional MSpeaker II/CP50/CPE40
Accessories • Content Sharing Device: WPP / VCH51
• Bracket: Wall/Rack
Controller Touch Panel: CTP18/CTP25
Content Sharing • VCH51: HDMI/USB-C, до 4Kp30
• WPP30: до 4Kp30
NAT and Firewall • ICE/TURN/STUN, H.460, NAT (manual/auto)
Network and Security • Wi-Fi 2.4/5 ГГц, BT 5.0, IPv4&IPv6
• Protocol: H.323/SIP
• SRTP/TLS/AES 256, QoS, 802.1X, LLDP-MED, VLAN
Physical • 3 × HDMI out (4K30), 1 × VCH/LAN
```
**Ловушка:** PDF разбивает заголовки по буквам — `Chips and System s`, `Camer a`,
`Firewal l Travers al`. Простой парсер сломается. Нужна нормализация склеенных слов.
---
## 3. Предлагаемый формат (наша схема)
```yaml
device:
vendor: yealink
model: MeetingEye 500
family: MeetingEye # для группировки
type: codec # codec | camera | mic | speaker | hub | touch | board
source: # провенанс (обязательно)
file: "Yealink MeetingEye 500 Datasheet.pdf"
page: 2
extracted: pdftotext
verified: false # без этого поля устройство не попадает в подбор
specs:
cpu: "4-core 2.6G + 4-core 2G"
ai_power: "4T"
os: "Android 11"
camera_support: [UVC84, UVC85, UVC86] # нормализовано в список
camera_max: 3
mic_support: [VCM35, VCM38, CP50, CPE40]
speaker_support: ["MSpeaker II", CP50, CPE40]
touch_support: [CTP18, CTP25]
content_sharing: [VCH51, WPP30]
protocols: [H.323, SIP, H.460]
nat: [ICE, TURN, STUN]
network: ["Wi-Fi 2.4/5", "Bluetooth 5.0", "IPv4", "IPv6"]
ports:
- {type: HDMI, count: 3, direction: out, max: 4K30}
- {type: VCH, count: 1, note: "VCH/LAN"}
security: [SRTP, TLS, AES-256, 802.1X, LLDP-MED, VLAN]
```
### Ключевые решения
1. **`source` обязателен** — без провенанса поле бесполезно (через месяц не проверить).
2. **Списки, а не строки** — `camera_support: [UVC84, UVC85]` позволяет строить граф
совместимости: «этот кодек работает с этими камерами».
3. **`verified: false`** по умолчанию — ручная проверка включает устройство в подбор.
4. **`type`** — кодек/камера/микрофон/хаб: без этого не построить правила совместимости.
---
## 4. Как парсить (порядок, по убыванию надёжности)
| Шаг | Метод | Почему |
|---|---|---|
| 1 | `pdfplumber` — извлечение таблиц | в PDF реальные таблицы, а не текст |
| 2 | нормализация склеенных слов (`Chips and System s` → `Chips and Systems`) | иначе поля не находятся |
| 3 | regex извлечение моделей (`UVC\d+`, `CTP\d+`, `VCM\d+`) в списки | даёт граф совместимости |
| 4 | LLM (локальная) — только для нестандартных разделов | 7B справляется с текстом, но не с числами |
| 5 | **сверка с pdftotext** — LLM не единственный источник | перекрёстная проверка |
**Правило:** числа (порты, разрешения, количество) — только regex/таблицы, не LLM.
LLM — для описаний и нестандартных формулировок.
---
## 5. Первый шаг (что делаю следующим)
1. Скрипт `harvest.py`: обход `Work/Datasheet/Yealink/**`, отбор `*Datasheet*.pdf`
2. Извлечение таблицы «Параметр → Описание» через `pdfplumber`
3. Нормализация склеенных слов
4. Запись в `devices/<vendor>/<model>.yaml` с провенансом
5. Отчёт: какие модели распознаны полностью, какие частично, что пропущено
**Критерий:** 5 даташитов разобраны, поля проверены глазами, схема зафиксирована.
---
## 6. Зачем это «комбайн», а не один инструмент
Даташит — только вход. Дальше:
```
даташит → спецификации → граф совместимости → подбор → покрытие → BOM → КП
```
Формат должен обслуживать **все** шаги. Поэтому:
- `camera_support` — не текст, а ссылки на другие устройства (граф)
- `type` — для правил («к кодеку нужен хотя бы один микрофон»)
- провенанс — чтобы объяснить клиенту, откуда цифра
Каждый следующий шаг добавляет поля, но **не меняет основу**.