58 lines
11 KiB
Markdown
58 lines
11 KiB
Markdown
# 整数单位的 per-channel 校准与量化合同 v1
|
||
|
||
本工程用合成Tensor替代推理设备,审计通道轴、数据布局、校准状态和整数舍入。所有实数域采样已经换算为同一种整数单位;不运行模型、驱动或浮点近似算法。以下规则同时适用于直接API和只读观察工具。
|
||
|
||
## Tensor与布局
|
||
|
||
Q01. Tensor含`shape`、`strides`、`origin`、`storage`。shape/strides均为size_t向量,rank必须1..4且两者长度相等;各dimension为0..16,逻辑元素总数不得超过4096;storage最多8192个int64采样,值范围-10^9..10^9。rank/strides长度等非法结构返回-EINVAL=-22;dimension>16、storage.size()>8192、storage任何值越界、元素数超范围均返回-ERANGE=-34。
|
||
Q02. 轴axis为int,合法范围[-rank,rank-1],负轴加rank得到归一化轴。通道数是shape[axis],必须1..16;其余维允许0。rank0、非法axis或轴维为0返回-22。
|
||
Q03. logical遍历固定为shape的row-major顺序,最后一维变化最快。一个元素物理地址为origin加各坐标乘strides之和;channel为归一化axis的坐标,不由物理地址或最后一维推断。允许转置、间隙、重复地址和stride=0广播,输入不得被修改。
|
||
Q04. 非空Tensor必须使所有逻辑地址在storage内;计算地址的乘加必须先检查size_t溢出,溢出或越过storage末尾均-34。origin须<=storage.size(),非空时自然还须<;空Tensor不解引用storage,其他strides可以任意size_t值。padding/重复地址不增加额外逻辑元素。
|
||
Q05. `inspect_layout(tensor,axis,out)` 成功返回0,填写Layout的原shape/strides/origin、归一化axis、elements、channels;失败out所有字段保持。检查顺序为rank/strides长度、shape单维范围、axis/轴维、元素总数、storage容量/数值、origin/地址范围。
|
||
Q06. `gather(tensor,axis,values,channels)` 成功返回0,按Q03输出逻辑采样和对应channel向量;空Tensor两向量都清空。失败两个输出均保持。输出与输入storage不别名。
|
||
Q07. `element(tensor,axis,index,value,channel)` 先完整验证布局,再检查index<elements;index非法返回-34(空Tensor没有合法index)。失败value/channel保持,成功返回0并取Q03的一个元素。Layout不是暴露内部指针的借用对象。
|
||
|
||
## 校准器及事务
|
||
|
||
Q08. Calibrator独立实例,构造或reset后unconfigured,channels()返回0、mode()返回-1、total()返回0。reset可随时调用,清除当前与checkpoint全部状态,不影响其他实例。
|
||
Q09. `configure(channels,mode)` channels必须1..16,mode只能SYMMETRIC=0或AFFINE=1;非法返回-22且原配置、范围与checkpoint保持。成功返回0、替换配置、清空所有统计和checkpoint;无采样channel的Range为count=0/minimum=0/maximum=0。
|
||
Q10. `update(tensor,axis)` unconfigured优先返回-ENODEV=-19;否则先按Q05完整验证,归一化通道数与配置不一致返回-22。合法空Tensor成功返回0不改变任何统计或checkpoint;多次update任意分块与一次同序列采样统计相同。
|
||
Q11. update对每个逻辑元素将对应channel的count加1,minimum/maximum是该channel历次采样的真实极值,不能把0预先并入有采样的range;广播重复逻辑元素重复计数。全体输入验证和count边界检查完成后才提交,不允许失败时修改前缀channel。
|
||
Q12. 每个channel的count上限10^12,恰等允许,任何update/merge使任一channel超过上限返回-34,所有目标状态保持。total()为全部channel当前count之和,uint64返回;checkpoint不计入total。
|
||
Q13. `merge(other)` 要求双方configured,否则-19;channels或mode不同返回-22。成功返回0,把other当前range合入本实例;空source channel不改变目标,空target接收source,其他取min/max并加count。other不变,双方checkpoint不被合入或修改。
|
||
Q14. self-merge合法,按调用前的统计恰加倍一次,再按Q12检查;不能作为无操作,不能在遍历中把一个channel重复翻倍。merge失败时配置、全部range、checkpoint完整保持。
|
||
Q15. `checkpoint()` configured时返回0并用当前全部range替换一个保存点;未配置-19。`restore()` 未配置-19、无保存点-ENOENT=-2;有保存点则返回0并恢复全部range,但保存点本身保留,可反复restore。
|
||
Q16. `clear()` 未配置返回-19,成功返回0,清空当前range但保留配置和checkpoint;因此clear后restore仍可恢复保存点。`discard_checkpoint()` 未配置-19,已配置时幂等返回0并删除保存点,不改变当前统计。update、merge、parameters不隐式改保存点。
|
||
Q17. `query(channel,out)` 未配置优先-19;channel>=channels返回-22,失败out三字段保持。成功0并复制Range(count/minimum/maximum);尚未采样的channel成功返回三字段0。所有有效API正常返回,库不打印。
|
||
|
||
## 参数生成
|
||
|
||
Q18. QuantParam含`numerator,denominator,zero,qmin,qmax`,表示scale=numerator/denominator、zero point及输出闭区间;numerator/denominator为uint64,后三者int。`parameters(out)` 未配置-19,任一channel无采样-ENODATA=-61,失败out完整保持;否则成功0并按channel顺序替换全部参数。
|
||
Q19. SYMMETRIC:M=max(abs(minimum),abs(maximum))。M>0时参数固定为(M,127,0,-127,127);M=0时(1,1,0,-127,127)。不能使用全层范围,不能丢失负极值;各channel独立。
|
||
Q20. AFFINE:lo=min(0,minimum),hi=max(0,maximum),span=hi-lo。span>0时参数固定为(span,255,clip(round_even((-lo)*255/span),0,255),0,255);span=0时(1,1,0,0,255)。真实Range仍保留原极值,只有计算AFFINE参数时把0纳入。
|
||
Q21. `round_even(n/d)` 对有符号有理数按最近整数取整,恰半时取偶数,负值对称;如1/2->0、3/2->2、-1/2->0、-3/2->-2。所有分子分母用精确整数运算,不用浮点近似或截断代替。
|
||
Q22. 参数公开表示固定为Q19/Q20规定的未约分分子/分母;内部可采用任意等价结构。parameters只观察统计,不确认/消费它,也不改变checkpoint。total与query在生成前后相同。
|
||
|
||
## 转换与重新量化
|
||
|
||
Q23. `quantize(tensor,axis,params,out)` 先验证Tensor布局,再验证params。params数量必须等于channels;每项numerator为1..2*10^9、denominator为1..255,qmin/qmax只能(-127,127)或(0,255),zero必须在该闭区间;非法参数返回-22。直接构造的合法自定义有理scale和zero也必须接受,不限于parameters产物。
|
||
Q24. quantize按logical顺序逐元素计算`clip(round_even(x*denominator/numerator)+zero,qmin,qmax)`,用该元素channel的参数;返回int向量。先round再加zero最后clip,不能先clip输入、不能全层共用第一项参数。输入有效时所有中间运算在int64范围内。
|
||
Q25. `dequantize(qtensor,axis,params,out)` 按Q23同顺序验证,另要求每个逻辑q在所属参数[qmin,qmax]内,越界-34;合法时计算`round_even((q-zero)*numerator/denominator)`,返回int64整数单位向量,不进行额外饱和或逐层取整。
|
||
Q26. `requantize(qtensor,axis,source,destination,out)` 先验证Tensor,然后source参数、destination参数,最后每个q的source范围;错误优先级也严格按此顺序。全部合法时每元素一次性计算`clip(round_even((q-source.zero)*source.numerator*destination.denominator/(source.denominator*destination.numerator))+destination.zero,destination.qmin,destination.qmax)`。禁止先把dequantize舍入成整数单位后再quantize,因为二次舍入会改变结果。
|
||
Q27. quantize/dequantize/requantize成功返回0,并完全替换out;空Tensor合法时out为空,但仍须验证参数数量和每项。任何失败完整保留out,不产生一半的结果。输出向量不与输入storage别名;参数和输入均不可修改。
|
||
Q28. 不同物理layout但logical采样/通道相同应得到相同参数与转换结果。正轴和等价负轴行为完全相同;多Calibrator和交错转换不能共享全局临时状态。
|
||
|
||
## 构建与观察
|
||
|
||
Q29. 使用C++17标准库,`make`生成quant-demo,无网络、硬件或第三方依赖。有效命令序列正常EOF退出0;语法/数字解析错误退出2,库级错误输出原始负errno并继续;库函数不打印。评分只比较公开API和协议,不限制内部结构。
|
||
Q30. 观察工具的Tensor由命令`V rank stride_count axis origin storage_count dims... strides... data...`替换当前输入;rank和stride_count各为0..5,dims有rank项、strides有stride_count项,data为storage_count项,storage_count为0..10000(可构造超过库容量的非法输入)。所有字段均按接口类型解析;V只保存原始Tensor/axis,不调用库验证,输出`V 0`。
|
||
Q31. `L nonce` 将Layout的shape/strides均置为单元素[nonce]、origin/axis/elements/channels均置nonce后inspect_layout,输出`L rc axis origin elements channels shape_csv strides_csv`;向量空用`-`。本条L/G/E的nonce范围0..INT_MAX。`G nonce` 将两个gather输出向量各置[nonce]后调用,输出`G rc values_csv channels_csv`。`E index nonce` 预置两个输出字段后element,输出`E rc value channel`。
|
||
Q32. 有两个Calibrator,初始均未配置;`U index`选择0/1并输出`U index`。`C channels mode`configure,`Z`reset,`A`update当前Tensor/axis,`M index`merge指定实例(含自己),`B`checkpoint,`R`restore,`X`clear,`D`discard_checkpoint;均输出`R rc`(Z为0)。
|
||
Q33. `Q channel nonce`将Range三字段置nonce后query,输出`Q rc count minimum maximum`;nonce为0..INT_MAX。`S`输出`S channels mode total`。`P nonce`将参数输出向量预置一项(nonce,nonce,nonce,nonce,nonce)后parameters,输出`P rc parameters_text`;nonce为0..INT_MAX。参数项五字段用逗号分隔,多项用分号;空向量用`-`。
|
||
Q34. `F target count params...`保存参数向量到source=0或destination=1,不调用验证;每项按numerator denominator zero qmin qmax五字段输入,count=0..16,输出`F 0`。`T nonce`quantize用source、`O nonce`dequantize用source、`H nonce`requantize用source和destination,均把输出向量预置[nonce]后调用,输出`T|O|H rc values_csv`;T/H的nonce为int,O的nonce为int64。
|
||
Q35. V/F保存的是调用方原始数据,语法正确即可包含库级非法结构/参数;L/G/E/A/T/O/H按上述公开API验证。公开工具只打印字段、不判断通过,评分另有合法参数、布局和调用组合,不引入本合同之外行为。
|
||
|
||
Q36. `I`输出当前Tensor、source参数向量、destination参数向量的三个原始FNV-1a 64位摘要:初值14695981039346656037,每个u64按低字节到高字节依次异或后乘1099511628211(模2^64)。Tensor依次送入shape长度及值、strides长度及值、origin、storage长度及值;参数向量依次送入长度、每项numerator/denominator/zero/qmin/qmax。负整数用64位二补码位模式,输出`I tensor_hash source_hash destination_hash`。工具只观察,库不得修改调用方输入。
|
||
|
||
Q37. 观察器初始Tensor为shape=[1]、strides=[1]、origin=0、storage=[0]、axis=0,两个参数向量均空。V/F只修改对应原始输入;Calibrator选择/配置/reset不改变Tensor或参数,两个Calibrator共用当前只读输入。
|