智能体处理表格前怎么定数据质量标准？用字段契约检查缺失、类型与范围

让智能体直接“清洗一下这张表”，往往会把业务规则藏在自然语言里。更可靠的起点是先写一份字段契约：哪些列必须存在、哪些值不能为空、数字允许什么范围、类别允许哪些取值。智能体可以提出处理建议，是否满足契约由确定性的程序判断。

先把质量标准写到字段级

下面的教学表有三列：记录编号、年龄和标签。假设年龄只接受 0～120，标签只接受 yes/no。unknown 不是年龄，151 超出约定范围，空标签也要报错。这些阈值是教学例子，实际项目应由数据负责人按业务定义。

不要把“缺失”与“非法值”混成一类：空标签需要补充或隔离；年龄字符串不能可靠转成数值时，需要回查原始记录；超范围年龄不应静默截断为 120。下面将错误写成“行、字段、原因”，后续处理才能定位。

运行一个最小字段契约

在 Python 3.11 环境安装 pandas 后，把代码保存为 quality_contract.py，执行 python quality_contract.py。示例数据在代码里构造，不会读取或上传你的实际表格。

import pandas as pd

# 人工构造的教学数据，非真实业务表。
rows = pd.DataFrame({'record_id':['A1','A2','A3'], 'age':['31','unknown','151'], 'label':['yes','no',None]})
contract = {'record_id':{'required':True}, 'age':{'required':True,'numeric':True,'min':0,'max':120}, 'label':{'required':True,'allowed':{'yes','no'}}}
issues=[]
for field, rules in contract.items():
    if field not in rows:
        issues.append({'row':'ALL','field':field,'issue':'missing_column'});continue
    for index,value in rows[field].items():
        row_id=rows.loc[index,'record_id']
        if pd.isna(value):
            if rules['required']:issues.append({'row':row_id,'field':field,'issue':'missing_value'})
            continue
        if rules.get('numeric'):
            number=pd.to_numeric(pd.Series([value]),errors='coerce').iloc[0]
            if pd.isna(number):issues.append({'row':row_id,'field':field,'issue':'invalid_number'})
            elif not rules['min'] <= number <= rules['max']:issues.append({'row':row_id,'field':field,'issue':'out_of_range'})
        if 'allowed' in rules and value not in rules['allowed']:
            issues.append({'row':row_id,'field':field,'issue':'unknown_category'})
print(pd.DataFrame(issues).to_string(index=False))
print('can_continue=',len(issues)==0)

根据错误报告决定下一步

运行结果会分别指出 A2 的年龄不是数字、A3 的年龄超范围及标签缺失，最后给出 can_continue=False。先核对这三行的源数据，再按业务规则修订或隔离；完成修订后重跑同一脚本，错误列表为空才继续建模或汇总。

row field          issue
 A2   age invalid_number
 A3   age   out_of_range
 A3 label  missing_value
can_continue= False

这里用 pd.to_numeric(..., errors='coerce') 识别不可转换的数值，不能把转换后的缺失值直接当零。关于缺失值表示和转换行为，可查看 pandas 缺失值指南与pandas 基础与类型说明。

边界：契约不能替代业务判断

字段契约能挡住格式错误，却不知道 151 是否因单位、录入或真实特殊人群产生。真实表格还应定义单位、时区、主键和跨字段规则，并保留原始数据。若字段名称发生变化，本例会报整列缺失；不要让智能体猜一个相近列名后自动继续。