58 lines
11 KiB
Markdown
Raw 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.

# 整数单位的 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共用当前只读输入。