简介围绕Python与人工智能技术构建的智能联系人管理毕业设计面向计算机相关专业毕业生、课程设计学习者及希望积累AI落地经验的开发者可用于联系人信息增删改查、检索分类、导入导出及基于行为模式的智能推荐等场景。压缩包共50个文件、约141.21MB涵盖7个Python源码与10个字节码文件、8个界面文件、6个HTML页面以及说明文档、Excel数据、图片素材和可执行程序分别对应核心逻辑、界面布局、图表展示、设计说明与免环境运行。已有615人学习下载。读者可据此梳理系统架构与交互流程参考自然语言查询和行为预测功能的实现思路并结合开发文档中的设计、测试说明完成调试、答辩准备与二次开发。1. 通讯录里三千个联系人怎么让这套毕设的“智能”站得住答辩现场最容易被问住的一句话是“你这个智能体现在哪”。A 同学做的是毕业设计里的 AI 智能联系人管理程序Python 写的增删改查齐全界面也干净但只靠这些评委一句“这不就是个大作业”就能把整份工作压回去。真正让这套方案立起来的是三件事把微信备注、名片转出的文本、Excel 导出的脏数据统一成结构化记录用拼音全拼、首字母和同音字模糊匹配把“张伟”“章伟”“zhangwei”搜成同一个人再按往来频次和标签给出“该联系谁”的提醒。这份 Python 源代码加开发文档说明适合拿它交毕设、做课程设计也适合想快速跑通一个可演示原型的开发者。2. 需求拆解与技术选型为什么不上大模型也能叫 AI2.1 先把功能边界划死必做项与加分项做联系人管理这类题目最容易犯的错是功能清单越写越长最后什么都做了个开头。我的做法是先划一条线答辩时必须能现场演示跑通的是必做项讲得出来、代码里有痕迹、但可以只做半成品的是加分项明确写进文档“不在本期范围”的是排除项。这条线划完后面所有模块设计都有依据开发文档说明里也有了“需求分析”章节的骨架。必做项我一般定成六块联系人的增删改查与回收站、CSV 与 vCard 导入导出、多条件筛选与排序、分组与标签、拼音与模糊检索、操作日志。这六块撑起一个完整可用的系统任何一块缺失演示流程就会断。加分项是这套方案区别于普通通讯录的地方智能去重合并同名同号、同号不同名、同邮箱跨公司、基于规则的意图识别“帮我找上周联系过的客户”、关系热度排序、生日与跟进提醒、联系人关系图谱。加分项不必全做完挑两三个做透比五个都做一半更容易在答辩时讲出深度。排除项必须写清楚这恰恰是加分的地方。真实社交平台的数据抓取不碰一是合规风险二是演示时网络不通就翻车端到端微调大模型不做一台笔记本跑不动训练时间也撑不住进度人脸识别头像匹配不做样本量不够效果没法看。把这三点写进文档的“范围限定”评委反而会觉得你想清楚了。2.2 技术栈取舍Flask SQLite 中文处理三件套选型的核心原则是“能在评委的笔记本上双击跑起来”。Django 功能全但目录结构重、启动慢一个联系人管理项目用不上它的 admin 和 ORM 全家桶FastAPI 性能好、自带接口文档但对不熟悉异步的学生来说一个await写漏就报错排查成本高。Flask 的权衡点最好路由直观、蓝图能拆模块、调试模式下的报错页足够友好一个app.py加几个蓝图就能把后端撑起来。数据层用 SQLite。这不是偷懒而是这类单机演示型系统的合理选择零配置、单文件、拷走就能跑答辩换台电脑也不用重新装数据库。真实场景下并发写入确实会成为瓶颈但联系人管理是典型的读多写少一个人用根本压不出问题这一点在文档里写清楚就行。中文处理是这套方案的技术核心。“智能”两个字能不能立住八成靠这三个库jieba做备注和公司名的分词用于关键词提取和标签推荐pypinyin生成全拼和首字母解决“输入法打不出字”的检索场景rapidfuzz做字符串相似度计算比标准库的difflib快一个量级几万条记录做实时匹配也不卡。# 后端框架与跨域前后端分离时前端联调用 flask flask-cors # 数据层 sqlalchemy # 中文分词、拼音转换、模糊匹配 jieba pypinyin rapidfuzz # 导入导出Excel 与 Word 报告 openpyxl python-docx依赖清单里故意不锁版本号。毕设交付的代码要在不同机器上跑锁死版本反而容易在别人的环境里装不上真要做可复现就在文档里附一份pip freeze的实际输出作为附录正文里不写死。提醒一句pypinyin和rapidfuzz都是纯 Python 或带预编译包的库pip install基本不会卡在编译环节这对答辩前一周还在装环境的同学很关键。凡是需要本地编译 C 扩展的库能不用就不用。2.3 数据模型五张表撑起整个系统表结构设计得对不对直接决定了后面去重、检索、统计这些功能写起来是顺还是别扭。我的经验是别急着上“大而全”的联系人表先按职责拆一张主表存人一张表存标签一张关联表做多对多一张表记录交互一张表留合并痕迹。-- 联系人主表 CREATE TABLE contact ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, name_pinyin TEXT, -- 全拼如 zhangwei name_initials TEXT, -- 首字母如 zw phone TEXT, -- 归一化后的号码去掉空格横线 email TEXT, org TEXT, -- 公司或组织 title TEXT, -- 职位 remark TEXT, -- 备注原文分词后做标签推荐 birthday TEXT, -- ISO 日期便于计算提醒 heat INTEGER DEFAULT 0, -- 关系热度交互表定期回写 created_at TEXT DEFAULT (datetime(now,localtime)), updated_at TEXT, is_deleted INTEGER DEFAULT 0 -- 软删除回收站靠它 ); -- 检索加速拼音与首字母各建一个索引 CREATE INDEX idx_contact_pinyin ON contact(name_pinyin); CREATE INDEX idx_contact_initials ON contact(name_initials); CREATE INDEX idx_contact_phone ON contact(phone); -- 标签表与关联表 CREATE TABLE tag ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT UNIQUE NOT NULL, color TEXT DEFAULT #4a90d9 ); CREATE TABLE contact_tag ( contact_id INTEGER NOT NULL, tag_id INTEGER NOT NULL, PRIMARY KEY (contact_id, tag_id) ); -- 交互记录谁在什么时候通过什么方式联系过 CREATE TABLE interaction ( id INTEGER PRIMARY KEY AUTOINCREMENT, contact_id INTEGER NOT NULL, channel TEXT, -- call / mail / meeting / other happened_at TEXT, note TEXT ); -- 合并日志去重操作必须留痕否则误合并无法回滚 CREATE TABLE merge_log ( id INTEGER PRIMARY KEY AUTOINCREMENT, from_id INTEGER, to_id INTEGER, payload TEXT, -- 被合并记录的 JSON 快照 merged_at TEXT DEFAULT (datetime(now,localtime)) );几个设计点值得在文档里单独说明。第一name_pinyin和name_initials是冗余字段写入时由代码生成而不是靠数据库函数原因是 SQLite 没有内置拼音函数把计算放在应用层更可控代价是每次改名要同步更新两个字段这一点用模型层的before_save钩子统一处理。第二is_deleted用软删除而不是物理删除。通讯录这种数据误删一个客户可能意味着丢掉一条重要线索回收站是必需品而不是加分项。所有查询默认带is_deleted 0可以用 SQLAlchemy 的event.listens_for挂一个全局过滤避免每个查询手写条件。第三merge_log存的是被合并记录的完整 JSON 快照。这一条是我踩过坑之后加的早期版本只记了from_id和to_id结果演示时误合并了两条记录想恢复发现原数据已经被删了只能重装数据库。有了快照一句INSERT就能把人还原回来这叫给自己留后悔药。第四heat字段是冗余的统计值不是实时算的。每次打开列表都去interaction表做聚合几千条还行上万条就明显卡顿。通常的做法是加一个定时任务每天凌晨跑一次UPDATE contact SET heat (...)或者在写入交互记录时同步累加。前者一致性更好后者实时性更好演示场景选后者足够。3. 总体架构设计三层结构与一个可讲清的目录3.1 分层与目录结构这套系统我按三层组织接口层负责收参数、校验、返回 JSON服务层放业务逻辑模糊检索、去重、意图解析都在这一层数据层封装模型和查询。三层之间单向依赖接口层不直接碰数据库服务层不关心 HTTP 状态码。这样做的好处很直接答辩时评委问“如果换成 Web 端或者桌面端怎么办”你可以指着服务层说“这一层不用改只换接口层”。contact_ai/ ├── app.py # 应用入口注册蓝图、初始化数据库 ├── config.py # 路径、阈值、分页大小等可调参数 ├── requirements.txt ├── models/ │ ├── __init__.py # 声明 db 实例避免循环导入 │ ├── contact.py # 联系人、标签、关联表 │ └── interaction.py # 交互记录与合并日志 ├── services/ │ ├── normalize.py # 手机号、邮箱、日期的归一化 │ ├── pinyin.py # 全拼与首字母生成含多音字表 │ ├── search.py # 模糊检索与打分排序 │ ├── dedupe.py # 相似度计算与合并策略 │ └── intent.py # 规则意图识别与槽位抽取 ├── api/ │ ├── contact_api.py # 联系人相关路由 │ ├── import_api.py # 导入导出路由 │ └── assistant_api.py # 智能问答路由 ├── static/ # 前端静态资源 ├── templates/ # 页面模板 ├── data/ │ └── contact.db # SQLite 数据文件 └── docs/ # 开发文档说明的源文件目录划分有个小技巧models里用__init__.py声明db实例其他模块统一从这里导入。Flask 项目最常见的一类报错就是循环导入app.py导入modelsmodels又反过来导入app.py里的app结果启动就崩。把db单独拎出来链条就断了这种结构性问题的成本远低于事后排查。config.py里放几个必须可调的参数答辩时可以现场改给人看模糊匹配的相似度阈值、检索返回条数上限、去重的合并阈值、列表默认分页大小。把这些硬编码在代码里的数字抽到配置里一是演示时能说明“参数可调”二是写文档时可以直接列成参数表。3.2 接口约定把后端能力摊开成一张路由表前后端分离的写法在毕设里越来越常见但很多人只约定了 URL没约定返回结构前端每个页面都要写一套解析逻辑。我的做法是统一包一层响应体code表示业务状态message给人看data放实际内容。这样前端只写一个请求封装函数异常提示也统一了。方法路径说明关键参数GET/api/contacts分页列表支持筛选排序pagesizetagsortPOST/api/contacts新建联系人namephoneorg等PUT/api/contacts/id更新联系人同新建字段可部分传DELETE/api/contacts/id软删除进回收站无GET/api/search智能检索qlimitmodePOST/api/import/csv导入 CSVfileencodingGET/api/export/vcf导出 vCardtag可选POST/api/dedupe/scan扫描疑似重复thresholdPOST/api/dedupe/merge执行合并keep_iddrop_idsPOST/api/assistant自然语言指令text这张表在开发文档说明里可以直接当“接口设计”章节的主体。表格比大段文字更能体现工作量也方便答辩时快速翻到某一页回答提问。注意GET /api/search的mode参数我留了exact、pinyin、fuzzy三个取值默认走混合模式这个设计让“模糊检索”这个功能点在演示时可以分三档展示对比效果一目了然。3.3 开发文档说明怎么写把代码翻译成章节源代码和文档是两份交付物很多人代码写得不错文档却写成流水账。我的经验是按“问题—方案—验证”三段式组织每一章让文档读起来像一份技术决策记录而不是代码注释的搬运。文档章节对应代码位置要写清的核心内容需求分析无三类用户场景、必做与排除项、功能清单表总体设计app.py、config.py三层架构图、模块职责、目录说明数据设计models/五张表的字段含义、索引理由、冗余字段取舍关键算法services/拼音生成、相似度公式、意图规则表接口设计api/路由表、请求响应示例、错误码测试与验收tests/或手工用例用例表、边界数据、性能数字写“关键算法”这一章时别只贴代码。每段代码前面用两三句话交代“为什么这么设计”后面用一句话交代“失败了会怎样”。比如拼音检索那节要写清多音字怎么处理、匹配不上时降级到什么策略评委顺着这几句话追问你就有话可接。4. 核心功能实现从脏数据到能搜得准的联系人4.1 导入清洗脏数据是这套系统的第一道坎真实场景里的联系人数据有多脏做过的人都有体会。从表格导出的手机号可能带空格、带横线、带86前缀也可能被 Excel 自动转成科学计数法姓名里混着全角空格和不可见字符公司名有“有限公司”“有限责任公司”“有限责任公司分公司”三种写法指同一家。导入环节不做清洗后面的检索和去重全是白费。import re from pypinyin import lazy_pinyin, Style # 只保留数字和可选的前导加号其余字符一律剔除 PHONE_CLEAN_RE re.compile(r[^\d]) # 全角空格、零宽字符、制表符这些肉眼看不见但会让匹配失败 INVISIBLE_RE re.compile(r[\u3000\u200b-\u200f\t\r\n]) def normalize_phone(raw: str) - str: 归一化手机号去分隔符、去国际区号、去前导 0 if not raw: return s PHONE_CLEAN_RE.sub(, str(raw).strip()) if s.startswith(0086): s s[4:] elif s.startswith(86): s s[3:] elif s.startswith(86) and len(s) 13: s s[2:] return s.lstrip(0) if len(s) 11 else s def normalize_name(raw: str) - str: 归一化姓名去不可见字符、合并多余空格 if not raw: return s INVISIBLE_RE.sub(, str(raw)) return re.sub(r\s, , s).strip() def build_pinyin(name: str): 生成全拼与首字母供检索字段使用 full .join(lazy_pinyin(name)).lower() initials .join(lazy_pinyin(name, styleStyle.FIRST_LETTER)).lower() return full, initialsnormalize_phone里那个lstrip(0)需要解释一下。Excel 导出的号码经常带前导 0比如某些座机写法而手机号本身不以 0 开头所以长度超过 11 位时去掉前导 0 是安全的长度不足 11 位则保留避免把座机号改坏。这种“按长度分支”的判断看着啰嗦但它挡住的是导入后一批号码全废的事故。INVISIBLE_RE里列的那几个 Unicode 区间是从微信复制粘贴过来的重灾区。零宽字符在编辑器里完全看不见但它会让“张伟”和“张伟”判成两个不同的字符串去重算法直接失效。这类问题不看原始字节根本发现不了属于典型的玄学 bug我的建议是导入入口统一过一遍清洗函数别指望在每个用到的地方补。清洗之后还有一个落库前的校验手机号长度不在 7 到 15 位之间的标记为待确认而不是直接丢弃邮箱不符合基本格式的保留原值但打上invalid标记。直接丢弃脏数据的做法看似干净实际上会让用户以为导入丢了人体验更差。4.2 智能检索拼音、首字母与模糊打分的三层排序检索是这套系统里用户感知最强的功能。手机自带通讯录的检索其实已经不错你要做的是在“记不清字怎么写”这个场景上做得更好。我的实现分三层精确命中排最前拼音与首字母命中排中间模糊相似度命中排最后三层的分数加权后统一排序。from rapidfuzz import fuzz # 三层权重精确 拼音 模糊总和为 1.0 W_EXACT, W_PINYIN, W_FUZZY 0.5, 0.3, 0.2 def score_one(keyword: str, row: dict) - float: 给单条联系人打匹配分返回 0~1 kw keyword.strip().lower() if not kw: return 0.0 name (row.get(name) or ).lower() pinyin (row.get(name_pinyin) or ).lower() initials (row.get(name_initials) or ).lower() # 第一层姓名或拼音前缀完全命中直接给满分 if kw name or kw pinyin or kw initials: return 1.0 if name.startswith(kw) or pinyin.startswith(kw): return 0.9 # 第二层拼音与首字母的部分匹配 p_score max( fuzz.partial_ratio(kw, pinyin), fuzz.partial_ratio(kw, initials), ) / 100.0 # 第三层姓名的模糊匹配容忍错别字和顺序差异 f_score fuzz.ratio(kw, name) / 100.0 return W_EXACT * 0 W_PINYIN * p_score W_FUZZY * f_score def search(keyword: str, rows: list, limit: int 20, min_score: float 0.35): 返回按分数降序的检索结果低于阈值的直接过滤掉 scored [(score_one(keyword, r), r) for r in rows] scored [item for item in scored if item[0] min_score] scored.sort(keylambda x: (-x[0], x[1].get(name, ))) return scored[:limit]score_one里的权重是调出来的不是拍脑袋定的。早期版本三层平分结果搜“zhangwei”时一个备注里带“zhangwei”的无关联系人排到了真正的张伟前面。把精确匹配的权重压到 0.5 之后前缀命中直接返回 0.9排序就正常了。这类参数在文档里要写成“经验值可按数据规模调整”别写成“最优值”否则评委会追问依据。min_score设成 0.35 是个折中。设太高比如 0.6搜“李”会把“李娜”“李强”全过滤掉设太低比如 0.1搜什么都返回一大堆用户反而找不到人。通常的做法是先按数据量试几组把结果截图放进文档的测试章节这比空谈阈值有意义得多。还有一个容易忽略的点检索的候选集不要每次全表加载。search函数接收的是rows实际调用时应该先用 SQL 做一次粗筛比如WHERE name_pinyin LIKE ? OR name LIKE ?把候选集压到几百条以内再用 Python 做精细打分。全表加载一万条记录做fuzz.ratio单次请求能跑到几百毫秒列表页翻页时会明显卡顿。4.3 意图识别用规则加槽位做出“能听懂人话”的效果“智能助手”这个模块最容易做成噱头。真接一个大模型 API答辩现场网络一抖就尴尬自己训一个模型数据量根本不够。我的方案是用规则加槽位抽取覆盖通讯录场景里最高频的十几类指令效果稳定、响应在毫秒级、完全离线可跑。这套做法在文档里叫“轻量意图识别”讲起来比“调了个接口”扎实得多。import re # 意图规则表pattern 命中即认为属于该意图 INTENT_RULES [ (find_by_tag, re.compile(r(找|查|列出).{0,4}(客户|同事|朋友|同学))), (find_by_time, re.compile(r(上周|本周|上个月|最近|今天).{0,6}(联系|沟通|见过))), (find_by_company, re.compile(r(在|属于).{0,6}(公司|单位|部门))), (count_contact, re.compile(r(有多少|几个人|数量))), (birthday_soon, re.compile(r(生日|寿辰).{0,4}(快到|临近|这个月))), ] TIME_WORDS {今天: 0, 本周: 7, 上周: 14, 上个月: 30, 最近: 30} def parse_intent(text: str) - dict: 返回 {intent, slots}识别不出时返回 unknown t text.strip() for name, pattern in INTENT_RULES: if pattern.search(t): return {intent: name, slots: extract_slots(t)} return {intent: unknown, slots: extract_slots(t)} def extract_slots(text: str) - dict: 抽取时间、标签、公司等槽位抽不到就留空 slots {} for word, days in TIME_WORDS.items(): if word in text: slots[days] days break # 书名号或引号里的内容当作标签 m re.search(r[《「\](.?)[》」\], text) if m: slots[tag] m.group(1) # “在XX公司”这类结构取“在”之后到句末的片段 m re.search(r在(.{2,12}?)(公司|单位|部门|工作), text) if m: slots[org] m.group(1) return slots这套规则的关键不在正则写得多复杂而在“识别不出时怎么办”。parse_intent对未命中的输入返回unknown接口层此时不该报错而是降级成普通关键词检索把用户输入的原文当作q参数走一遍search。这个降级路径必须在文档里写明因为它是“系统健壮性”的体现也是答辩时能主动讲出来的设计考量。规则表里我特意把count_contact放在find_by_tag后面。顺序有讲究像“我有多少个客户”这句话两条规则都能命中如果计数规则在前就会被误判成查找。规则匹配是线性扫描先匹配到的赢所以更具体的规则要往前放。这个细节写进文档评委会认为你考虑过冲突消解。extract_slots里的时间词只做粗粒度映射不解析具体日期。原因是自然语言里的“上周三”歧义太大解析错了反而扣分。粗粒度映射到天数区间配合交互表的时间字段做范围查询准确率反而更高。这是典型的“宁可少做不可做错”。4.4 去重合并相似度加权与可回滚的合并流程重复联系人是通讯录用久了必然出现的问题同一个人存了两条一条是手机号一条是邮箱或者换了公司以后另存了一份。自动去重的难点不在算相似度而在“敢不敢自动合并”。我的策略是分两步走扫描阶段只标记疑似重复人工确认后才执行合并合并全程留痕可回滚。def similarity(a: dict, b: dict) - float: 加权相似度号码权重最高其次是姓名最后是公司 score 0.0 # 手机号完全一致基本可以认定是同一人直接给 0.6 if a.get(phone) and a.get(phone) b.get(phone): score 0.6 # 邮箱一致加 0.25很多人用同一个邮箱注册不同账号 elif a.get(email) and a.get(email) b.get(email): score 0.25 # 姓名完全一致给满分拼音一致给半分 if a.get(name) b.get(name): score 0.25 elif a.get(name_pinyin) and a.get(name_pinyin) b.get(name_pinyin): score 0.15 # 公司一致给 0.15一方为空时不给分也不扣分 if a.get(org) and b.get(org): if a[org] b[org]: score 0.15 else: score - 0.10 # 公司不同是强反证 return round(max(score, 0.0), 3) def scan_duplicates(rows: list, threshold: float 0.82) - list: 两两比较返回超过阈值的疑似重复对 pairs [] for i in range(len(rows)): for j in range(i 1, len(rows)): s similarity(rows[i], rows[j]) if s threshold: pairs.append({a: rows[i][id], b: rows[j][id], score: s}) pairs.sort(keylambda x: -x[score]) return pairsthreshold定在 0.82 是我在几百条模拟数据上试出来的号码一致加姓名一致就是 0.85能进只有号码一致是 0.6进不来避免把公司前台电话相同的一堆人全判成重复姓名拼音一致加公司一致是 0.30也进不来。这个阈值放在config.py里演示时调低到 0.6界面立刻刷出一堆疑似重复观感很直观。真正让合并功能站得住的是回滚。执行合并时先把被合并记录的完整字段序列化成 JSON 写进merge_log再把标签和交互记录迁移到保留的那条上最后软删除被合并的记录。误合并之后从日志里读回 JSON 重建一条记录标签关联也一并恢复。没有这一步去重功能在答辩现场就是个定时炸弹——评委只要问一句“合并错了怎么办”没准备的人当场卡住。批量扫描的复杂度是 O(n²)一万条记录就是五千万次比较纯 Python 跑起来要几十秒。优化办法是先按手机号分组只对号码相同或姓氏拼音相同的记录两两比较候选集能压到很小。这个优化写进文档的“性能分析”章节是很实在的一笔。5. 避坑与排查这套毕设最容易翻车的五个点5.1 多音字姓名搜不到现象搜“单老师”搜不出来联系人明明叫“单磊”搜“曾”也找不到姓曾的人。原因lazy_pinyin默认取最常见读音“单”被转成dan而不是姓氏读音shan“曾”被转成zeng而人名里常读ceng“解”“查”“仇”同理。检索按拼音字段匹配读音错了自然搜不到。解决维护一张小规模姓氏多音字表在build_pinyin里对首字做特判同时把多种读音都写进检索字段。我的做法是给name_pinyin存主读音另加一个name_pinyin_alt存备选读音检索时两个字段都参与匹配。表不用大覆盖二三十个常见多音姓氏就够写进文档还能当“细节处理”讲。5.2 Excel 导入后手机号面目全非现象导入的号码变成1.38001E10或者开头的 0 消失了或者尾数变成 0。原因Excel 会把长数字自动识别成数值型超过 11 位就转科学计数法前导 0 被当成无意义的数字去掉。用openpyxl读取时如果不指定单元格类型拿到的就是浮点数。解决读取时强制按文本处理cell.value取到后统一转str遇到科学计数法格式的字符串做一次还原int(float(s))。更稳妥的做法是在导入说明里要求用户先把该列设为文本格式代码里再兜一层。这个坑我在两个项目里都遇到过属于不看就必踩的类型。5.3 并发写入报 database is locked现象前端快速点几下保存后端日志里冒出sqlite3.OperationalError: database is locked。原因SQLite 默认的写锁是独占的同一时刻只允许一个写事务。Flask 开发服务器默认多线程两个请求同时写就冲突默认等待超时只有几秒超时就抛错。解决连接时指定timeout15让写操作多等一会写入走统一的会话管理用完立即提交并关闭别让事务悬着。如果确实有并发压力把journal_mode切成 WAL读写可以并行。文档里写清“单机演示场景下的取舍”比硬上 Postgres 诚实得多。5.4 模糊匹配把搜索结果搅成一锅粥现象搜“张伟”列表里第一个是“张伟明”真正要的“张伟”排在第五个搜两个字的名字返回的全是备注里提到这两个字的无关记录。原因fuzz.partial_ratio对短串天然友好“张伟”是“张伟明”的子串得分直接 100。备注字段没有限制权重备注里提一嘴的名字也参与了打分。解决区分字段权重姓名和拼音的匹配权重远高于备注短查询词两个字及以下优先走前缀匹配而不是子串匹配排序时加一个“长度差惩罚”长度差越大扣分越多。这三个调整加完排序基本就正常了。5.5 演示数据太干净现场导入真实文件就崩现象自己准备的 CSV 跑得好好的答辩时导师随手从手机导出一份通讯录丢过来程序直接报编码错误或者字段错位。原因真实导出的文件编码可能是 GBK 或带 BOM 的 UTF-8字段顺序和列名也和你预设的不一样还可能有合并单元格和空行。解决导入函数不要写死编码按utf-8-sig、utf-8、gbk的顺序逐个尝试全失败再报错列名做模糊映射比如“电话”“手机”“手机号”“联系方式”都映射到phone空行和缺少姓名的行直接跳过并记录到导入报告里。答辩前自己找两三份不同来源的文件跑一遍这半小时能省掉现场十分钟的尴尬。6. 验收与答辩把一份能跑的代码讲成一套能过的设计验收这一步很多人以为是最后写个“测试结论”就完事其实验收清单应该在做功能的时候同步写。我的习惯是每个模块做完立刻补三条用例正常输入、边界输入、异常输入。等到答辩前一周这些用例直接拼成验收表比临时补要省太多时间。验收项验收方法通过标准联系人增删改查手工操作加接口调用各一遍回收站可还原软删除不丢数据CSV 导入准备 UTF-8、GBK、带 BOM 三份文件三份都能导入字段映射正确拼音检索搜全拼、首字母、错别字各三次目标联系人均在前三条去重扫描造十组已知重复混入非重复召回不低于八组误报不超过一组意图识别准备二十条高频指令命中不低于十五条未命中降级不报错性能导入五千条后测列表与检索列表响应一秒内检索两秒内这张表在答辩时的用法是不要念直接投在屏幕上挑一行讲你测出过什么问题、怎么改的。“去重扫描误报了一组”这种坦诚比宣称“全部通过”更让人信服。答辩讲解的顺序我建议倒着来先演示一个具体场景——打开系统导入一份乱糟糟的 CSV搜“zw”找到张伟说一句“帮我找上周联系过的客户”列表刷出结果。三分钟演完评委会自己产生“这东西能干什么”的判断你再回头讲架构和数据表他们听得进去。反过来先讲三层架构讲到第二层就开始走神了。有个容易被忽略的加分点主动交代边界。讲完功能花一分钟说明哪些没做、为什么不做——不抓取真实社交平台数据是合规考虑不微调大模型是算力考虑不做人脸匹配是样本量考虑。这段话的作用是把“没做完”转化成“想清楚了”差别很大。还有一点源代码和开发文档说明要保持同步。我见过太多人代码改到最后一版文档还停在两周前字段名对不上、接口路径不一致评委翻两页就发现问题。我的做法是每次改动数据库字段或接口先改文档里的表再改代码顺序反了就会忘。从那以后我每次交方案前都会强制走一遍“换台电脑”流程清空环境只按文档里的步骤装依赖、初始化数据库、导入示例数据、跑一遍演示脚本。凡是文档里没写清、导致这一步卡住的地方全部当成 bug 修文档。这个习惯救过我至少两次其中一次是发现初始化脚本漏了创建索引五千条数据下检索慢了十倍自己机器上有旧库所以一直没暴露。希望这套结构能帮到你把手里那份代码讲成一份像样的方案。本文还有配套的精品资源点击获取
简介围绕Python与人工智能技术构建的智能联系人管理毕业设计面向计算机相关专业毕业生、课程设计学习者及希望积累AI落地经验的开发者可用于联系人信息增删改查、检索分类、导入导出及基于行为模式的智能推荐等场景。压缩包共50个文件、约141.21MB涵盖7个Python源码与10个字节码文件、8个界面文件、6个HTML页面以及说明文档、Excel数据、图片素材和可执行程序分别对应核心逻辑、界面布局、图表展示、设计说明与免环境运行。已有615人学习下载。读者可据此梳理系统架构与交互流程参考自然语言查询和行为预测功能的实现思路并结合开发文档中的设计、测试说明完成调试、答辩准备与二次开发。1. 通讯录里三千个联系人怎么让这套毕设的“智能”站得住答辩现场最容易被问住的一句话是“你这个智能体现在哪”。A 同学做的是毕业设计里的 AI 智能联系人管理程序Python 写的增删改查齐全界面也干净但只靠这些评委一句“这不就是个大作业”就能把整份工作压回去。真正让这套方案立起来的是三件事把微信备注、名片转出的文本、Excel 导出的脏数据统一成结构化记录用拼音全拼、首字母和同音字模糊匹配把“张伟”“章伟”“zhangwei”搜成同一个人再按往来频次和标签给出“该联系谁”的提醒。这份 Python 源代码加开发文档说明适合拿它交毕设、做课程设计也适合想快速跑通一个可演示原型的开发者。2. 需求拆解与技术选型为什么不上大模型也能叫 AI2.1 先把功能边界划死必做项与加分项做联系人管理这类题目最容易犯的错是功能清单越写越长最后什么都做了个开头。我的做法是先划一条线答辩时必须能现场演示跑通的是必做项讲得出来、代码里有痕迹、但可以只做半成品的是加分项明确写进文档“不在本期范围”的是排除项。这条线划完后面所有模块设计都有依据开发文档说明里也有了“需求分析”章节的骨架。必做项我一般定成六块联系人的增删改查与回收站、CSV 与 vCard 导入导出、多条件筛选与排序、分组与标签、拼音与模糊检索、操作日志。这六块撑起一个完整可用的系统任何一块缺失演示流程就会断。加分项是这套方案区别于普通通讯录的地方智能去重合并同名同号、同号不同名、同邮箱跨公司、基于规则的意图识别“帮我找上周联系过的客户”、关系热度排序、生日与跟进提醒、联系人关系图谱。加分项不必全做完挑两三个做透比五个都做一半更容易在答辩时讲出深度。排除项必须写清楚这恰恰是加分的地方。真实社交平台的数据抓取不碰一是合规风险二是演示时网络不通就翻车端到端微调大模型不做一台笔记本跑不动训练时间也撑不住进度人脸识别头像匹配不做样本量不够效果没法看。把这三点写进文档的“范围限定”评委反而会觉得你想清楚了。2.2 技术栈取舍Flask SQLite 中文处理三件套选型的核心原则是“能在评委的笔记本上双击跑起来”。Django 功能全但目录结构重、启动慢一个联系人管理项目用不上它的 admin 和 ORM 全家桶FastAPI 性能好、自带接口文档但对不熟悉异步的学生来说一个await写漏就报错排查成本高。Flask 的权衡点最好路由直观、蓝图能拆模块、调试模式下的报错页足够友好一个app.py加几个蓝图就能把后端撑起来。数据层用 SQLite。这不是偷懒而是这类单机演示型系统的合理选择零配置、单文件、拷走就能跑答辩换台电脑也不用重新装数据库。真实场景下并发写入确实会成为瓶颈但联系人管理是典型的读多写少一个人用根本压不出问题这一点在文档里写清楚就行。中文处理是这套方案的技术核心。“智能”两个字能不能立住八成靠这三个库jieba做备注和公司名的分词用于关键词提取和标签推荐pypinyin生成全拼和首字母解决“输入法打不出字”的检索场景rapidfuzz做字符串相似度计算比标准库的difflib快一个量级几万条记录做实时匹配也不卡。# 后端框架与跨域前后端分离时前端联调用 flask flask-cors # 数据层 sqlalchemy # 中文分词、拼音转换、模糊匹配 jieba pypinyin rapidfuzz # 导入导出Excel 与 Word 报告 openpyxl python-docx依赖清单里故意不锁版本号。毕设交付的代码要在不同机器上跑锁死版本反而容易在别人的环境里装不上真要做可复现就在文档里附一份pip freeze的实际输出作为附录正文里不写死。提醒一句pypinyin和rapidfuzz都是纯 Python 或带预编译包的库pip install基本不会卡在编译环节这对答辩前一周还在装环境的同学很关键。凡是需要本地编译 C 扩展的库能不用就不用。2.3 数据模型五张表撑起整个系统表结构设计得对不对直接决定了后面去重、检索、统计这些功能写起来是顺还是别扭。我的经验是别急着上“大而全”的联系人表先按职责拆一张主表存人一张表存标签一张关联表做多对多一张表记录交互一张表留合并痕迹。-- 联系人主表 CREATE TABLE contact ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, name_pinyin TEXT, -- 全拼如 zhangwei name_initials TEXT, -- 首字母如 zw phone TEXT, -- 归一化后的号码去掉空格横线 email TEXT, org TEXT, -- 公司或组织 title TEXT, -- 职位 remark TEXT, -- 备注原文分词后做标签推荐 birthday TEXT, -- ISO 日期便于计算提醒 heat INTEGER DEFAULT 0, -- 关系热度交互表定期回写 created_at TEXT DEFAULT (datetime(now,localtime)), updated_at TEXT, is_deleted INTEGER DEFAULT 0 -- 软删除回收站靠它 ); -- 检索加速拼音与首字母各建一个索引 CREATE INDEX idx_contact_pinyin ON contact(name_pinyin); CREATE INDEX idx_contact_initials ON contact(name_initials); CREATE INDEX idx_contact_phone ON contact(phone); -- 标签表与关联表 CREATE TABLE tag ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT UNIQUE NOT NULL, color TEXT DEFAULT #4a90d9 ); CREATE TABLE contact_tag ( contact_id INTEGER NOT NULL, tag_id INTEGER NOT NULL, PRIMARY KEY (contact_id, tag_id) ); -- 交互记录谁在什么时候通过什么方式联系过 CREATE TABLE interaction ( id INTEGER PRIMARY KEY AUTOINCREMENT, contact_id INTEGER NOT NULL, channel TEXT, -- call / mail / meeting / other happened_at TEXT, note TEXT ); -- 合并日志去重操作必须留痕否则误合并无法回滚 CREATE TABLE merge_log ( id INTEGER PRIMARY KEY AUTOINCREMENT, from_id INTEGER, to_id INTEGER, payload TEXT, -- 被合并记录的 JSON 快照 merged_at TEXT DEFAULT (datetime(now,localtime)) );几个设计点值得在文档里单独说明。第一name_pinyin和name_initials是冗余字段写入时由代码生成而不是靠数据库函数原因是 SQLite 没有内置拼音函数把计算放在应用层更可控代价是每次改名要同步更新两个字段这一点用模型层的before_save钩子统一处理。第二is_deleted用软删除而不是物理删除。通讯录这种数据误删一个客户可能意味着丢掉一条重要线索回收站是必需品而不是加分项。所有查询默认带is_deleted 0可以用 SQLAlchemy 的event.listens_for挂一个全局过滤避免每个查询手写条件。第三merge_log存的是被合并记录的完整 JSON 快照。这一条是我踩过坑之后加的早期版本只记了from_id和to_id结果演示时误合并了两条记录想恢复发现原数据已经被删了只能重装数据库。有了快照一句INSERT就能把人还原回来这叫给自己留后悔药。第四heat字段是冗余的统计值不是实时算的。每次打开列表都去interaction表做聚合几千条还行上万条就明显卡顿。通常的做法是加一个定时任务每天凌晨跑一次UPDATE contact SET heat (...)或者在写入交互记录时同步累加。前者一致性更好后者实时性更好演示场景选后者足够。3. 总体架构设计三层结构与一个可讲清的目录3.1 分层与目录结构这套系统我按三层组织接口层负责收参数、校验、返回 JSON服务层放业务逻辑模糊检索、去重、意图解析都在这一层数据层封装模型和查询。三层之间单向依赖接口层不直接碰数据库服务层不关心 HTTP 状态码。这样做的好处很直接答辩时评委问“如果换成 Web 端或者桌面端怎么办”你可以指着服务层说“这一层不用改只换接口层”。contact_ai/ ├── app.py # 应用入口注册蓝图、初始化数据库 ├── config.py # 路径、阈值、分页大小等可调参数 ├── requirements.txt ├── models/ │ ├── __init__.py # 声明 db 实例避免循环导入 │ ├── contact.py # 联系人、标签、关联表 │ └── interaction.py # 交互记录与合并日志 ├── services/ │ ├── normalize.py # 手机号、邮箱、日期的归一化 │ ├── pinyin.py # 全拼与首字母生成含多音字表 │ ├── search.py # 模糊检索与打分排序 │ ├── dedupe.py # 相似度计算与合并策略 │ └── intent.py # 规则意图识别与槽位抽取 ├── api/ │ ├── contact_api.py # 联系人相关路由 │ ├── import_api.py # 导入导出路由 │ └── assistant_api.py # 智能问答路由 ├── static/ # 前端静态资源 ├── templates/ # 页面模板 ├── data/ │ └── contact.db # SQLite 数据文件 └── docs/ # 开发文档说明的源文件目录划分有个小技巧models里用__init__.py声明db实例其他模块统一从这里导入。Flask 项目最常见的一类报错就是循环导入app.py导入modelsmodels又反过来导入app.py里的app结果启动就崩。把db单独拎出来链条就断了这种结构性问题的成本远低于事后排查。config.py里放几个必须可调的参数答辩时可以现场改给人看模糊匹配的相似度阈值、检索返回条数上限、去重的合并阈值、列表默认分页大小。把这些硬编码在代码里的数字抽到配置里一是演示时能说明“参数可调”二是写文档时可以直接列成参数表。3.2 接口约定把后端能力摊开成一张路由表前后端分离的写法在毕设里越来越常见但很多人只约定了 URL没约定返回结构前端每个页面都要写一套解析逻辑。我的做法是统一包一层响应体code表示业务状态message给人看data放实际内容。这样前端只写一个请求封装函数异常提示也统一了。方法路径说明关键参数GET/api/contacts分页列表支持筛选排序pagesizetagsortPOST/api/contacts新建联系人namephoneorg等PUT/api/contacts/id更新联系人同新建字段可部分传DELETE/api/contacts/id软删除进回收站无GET/api/search智能检索qlimitmodePOST/api/import/csv导入 CSVfileencodingGET/api/export/vcf导出 vCardtag可选POST/api/dedupe/scan扫描疑似重复thresholdPOST/api/dedupe/merge执行合并keep_iddrop_idsPOST/api/assistant自然语言指令text这张表在开发文档说明里可以直接当“接口设计”章节的主体。表格比大段文字更能体现工作量也方便答辩时快速翻到某一页回答提问。注意GET /api/search的mode参数我留了exact、pinyin、fuzzy三个取值默认走混合模式这个设计让“模糊检索”这个功能点在演示时可以分三档展示对比效果一目了然。3.3 开发文档说明怎么写把代码翻译成章节源代码和文档是两份交付物很多人代码写得不错文档却写成流水账。我的经验是按“问题—方案—验证”三段式组织每一章让文档读起来像一份技术决策记录而不是代码注释的搬运。文档章节对应代码位置要写清的核心内容需求分析无三类用户场景、必做与排除项、功能清单表总体设计app.py、config.py三层架构图、模块职责、目录说明数据设计models/五张表的字段含义、索引理由、冗余字段取舍关键算法services/拼音生成、相似度公式、意图规则表接口设计api/路由表、请求响应示例、错误码测试与验收tests/或手工用例用例表、边界数据、性能数字写“关键算法”这一章时别只贴代码。每段代码前面用两三句话交代“为什么这么设计”后面用一句话交代“失败了会怎样”。比如拼音检索那节要写清多音字怎么处理、匹配不上时降级到什么策略评委顺着这几句话追问你就有话可接。4. 核心功能实现从脏数据到能搜得准的联系人4.1 导入清洗脏数据是这套系统的第一道坎真实场景里的联系人数据有多脏做过的人都有体会。从表格导出的手机号可能带空格、带横线、带86前缀也可能被 Excel 自动转成科学计数法姓名里混着全角空格和不可见字符公司名有“有限公司”“有限责任公司”“有限责任公司分公司”三种写法指同一家。导入环节不做清洗后面的检索和去重全是白费。import re from pypinyin import lazy_pinyin, Style # 只保留数字和可选的前导加号其余字符一律剔除 PHONE_CLEAN_RE re.compile(r[^\d]) # 全角空格、零宽字符、制表符这些肉眼看不见但会让匹配失败 INVISIBLE_RE re.compile(r[\u3000\u200b-\u200f\t\r\n]) def normalize_phone(raw: str) - str: 归一化手机号去分隔符、去国际区号、去前导 0 if not raw: return s PHONE_CLEAN_RE.sub(, str(raw).strip()) if s.startswith(0086): s s[4:] elif s.startswith(86): s s[3:] elif s.startswith(86) and len(s) 13: s s[2:] return s.lstrip(0) if len(s) 11 else s def normalize_name(raw: str) - str: 归一化姓名去不可见字符、合并多余空格 if not raw: return s INVISIBLE_RE.sub(, str(raw)) return re.sub(r\s, , s).strip() def build_pinyin(name: str): 生成全拼与首字母供检索字段使用 full .join(lazy_pinyin(name)).lower() initials .join(lazy_pinyin(name, styleStyle.FIRST_LETTER)).lower() return full, initialsnormalize_phone里那个lstrip(0)需要解释一下。Excel 导出的号码经常带前导 0比如某些座机写法而手机号本身不以 0 开头所以长度超过 11 位时去掉前导 0 是安全的长度不足 11 位则保留避免把座机号改坏。这种“按长度分支”的判断看着啰嗦但它挡住的是导入后一批号码全废的事故。INVISIBLE_RE里列的那几个 Unicode 区间是从微信复制粘贴过来的重灾区。零宽字符在编辑器里完全看不见但它会让“张伟”和“张伟”判成两个不同的字符串去重算法直接失效。这类问题不看原始字节根本发现不了属于典型的玄学 bug我的建议是导入入口统一过一遍清洗函数别指望在每个用到的地方补。清洗之后还有一个落库前的校验手机号长度不在 7 到 15 位之间的标记为待确认而不是直接丢弃邮箱不符合基本格式的保留原值但打上invalid标记。直接丢弃脏数据的做法看似干净实际上会让用户以为导入丢了人体验更差。4.2 智能检索拼音、首字母与模糊打分的三层排序检索是这套系统里用户感知最强的功能。手机自带通讯录的检索其实已经不错你要做的是在“记不清字怎么写”这个场景上做得更好。我的实现分三层精确命中排最前拼音与首字母命中排中间模糊相似度命中排最后三层的分数加权后统一排序。from rapidfuzz import fuzz # 三层权重精确 拼音 模糊总和为 1.0 W_EXACT, W_PINYIN, W_FUZZY 0.5, 0.3, 0.2 def score_one(keyword: str, row: dict) - float: 给单条联系人打匹配分返回 0~1 kw keyword.strip().lower() if not kw: return 0.0 name (row.get(name) or ).lower() pinyin (row.get(name_pinyin) or ).lower() initials (row.get(name_initials) or ).lower() # 第一层姓名或拼音前缀完全命中直接给满分 if kw name or kw pinyin or kw initials: return 1.0 if name.startswith(kw) or pinyin.startswith(kw): return 0.9 # 第二层拼音与首字母的部分匹配 p_score max( fuzz.partial_ratio(kw, pinyin), fuzz.partial_ratio(kw, initials), ) / 100.0 # 第三层姓名的模糊匹配容忍错别字和顺序差异 f_score fuzz.ratio(kw, name) / 100.0 return W_EXACT * 0 W_PINYIN * p_score W_FUZZY * f_score def search(keyword: str, rows: list, limit: int 20, min_score: float 0.35): 返回按分数降序的检索结果低于阈值的直接过滤掉 scored [(score_one(keyword, r), r) for r in rows] scored [item for item in scored if item[0] min_score] scored.sort(keylambda x: (-x[0], x[1].get(name, ))) return scored[:limit]score_one里的权重是调出来的不是拍脑袋定的。早期版本三层平分结果搜“zhangwei”时一个备注里带“zhangwei”的无关联系人排到了真正的张伟前面。把精确匹配的权重压到 0.5 之后前缀命中直接返回 0.9排序就正常了。这类参数在文档里要写成“经验值可按数据规模调整”别写成“最优值”否则评委会追问依据。min_score设成 0.35 是个折中。设太高比如 0.6搜“李”会把“李娜”“李强”全过滤掉设太低比如 0.1搜什么都返回一大堆用户反而找不到人。通常的做法是先按数据量试几组把结果截图放进文档的测试章节这比空谈阈值有意义得多。还有一个容易忽略的点检索的候选集不要每次全表加载。search函数接收的是rows实际调用时应该先用 SQL 做一次粗筛比如WHERE name_pinyin LIKE ? OR name LIKE ?把候选集压到几百条以内再用 Python 做精细打分。全表加载一万条记录做fuzz.ratio单次请求能跑到几百毫秒列表页翻页时会明显卡顿。4.3 意图识别用规则加槽位做出“能听懂人话”的效果“智能助手”这个模块最容易做成噱头。真接一个大模型 API答辩现场网络一抖就尴尬自己训一个模型数据量根本不够。我的方案是用规则加槽位抽取覆盖通讯录场景里最高频的十几类指令效果稳定、响应在毫秒级、完全离线可跑。这套做法在文档里叫“轻量意图识别”讲起来比“调了个接口”扎实得多。import re # 意图规则表pattern 命中即认为属于该意图 INTENT_RULES [ (find_by_tag, re.compile(r(找|查|列出).{0,4}(客户|同事|朋友|同学))), (find_by_time, re.compile(r(上周|本周|上个月|最近|今天).{0,6}(联系|沟通|见过))), (find_by_company, re.compile(r(在|属于).{0,6}(公司|单位|部门))), (count_contact, re.compile(r(有多少|几个人|数量))), (birthday_soon, re.compile(r(生日|寿辰).{0,4}(快到|临近|这个月))), ] TIME_WORDS {今天: 0, 本周: 7, 上周: 14, 上个月: 30, 最近: 30} def parse_intent(text: str) - dict: 返回 {intent, slots}识别不出时返回 unknown t text.strip() for name, pattern in INTENT_RULES: if pattern.search(t): return {intent: name, slots: extract_slots(t)} return {intent: unknown, slots: extract_slots(t)} def extract_slots(text: str) - dict: 抽取时间、标签、公司等槽位抽不到就留空 slots {} for word, days in TIME_WORDS.items(): if word in text: slots[days] days break # 书名号或引号里的内容当作标签 m re.search(r[《「\](.?)[》」\], text) if m: slots[tag] m.group(1) # “在XX公司”这类结构取“在”之后到句末的片段 m re.search(r在(.{2,12}?)(公司|单位|部门|工作), text) if m: slots[org] m.group(1) return slots这套规则的关键不在正则写得多复杂而在“识别不出时怎么办”。parse_intent对未命中的输入返回unknown接口层此时不该报错而是降级成普通关键词检索把用户输入的原文当作q参数走一遍search。这个降级路径必须在文档里写明因为它是“系统健壮性”的体现也是答辩时能主动讲出来的设计考量。规则表里我特意把count_contact放在find_by_tag后面。顺序有讲究像“我有多少个客户”这句话两条规则都能命中如果计数规则在前就会被误判成查找。规则匹配是线性扫描先匹配到的赢所以更具体的规则要往前放。这个细节写进文档评委会认为你考虑过冲突消解。extract_slots里的时间词只做粗粒度映射不解析具体日期。原因是自然语言里的“上周三”歧义太大解析错了反而扣分。粗粒度映射到天数区间配合交互表的时间字段做范围查询准确率反而更高。这是典型的“宁可少做不可做错”。4.4 去重合并相似度加权与可回滚的合并流程重复联系人是通讯录用久了必然出现的问题同一个人存了两条一条是手机号一条是邮箱或者换了公司以后另存了一份。自动去重的难点不在算相似度而在“敢不敢自动合并”。我的策略是分两步走扫描阶段只标记疑似重复人工确认后才执行合并合并全程留痕可回滚。def similarity(a: dict, b: dict) - float: 加权相似度号码权重最高其次是姓名最后是公司 score 0.0 # 手机号完全一致基本可以认定是同一人直接给 0.6 if a.get(phone) and a.get(phone) b.get(phone): score 0.6 # 邮箱一致加 0.25很多人用同一个邮箱注册不同账号 elif a.get(email) and a.get(email) b.get(email): score 0.25 # 姓名完全一致给满分拼音一致给半分 if a.get(name) b.get(name): score 0.25 elif a.get(name_pinyin) and a.get(name_pinyin) b.get(name_pinyin): score 0.15 # 公司一致给 0.15一方为空时不给分也不扣分 if a.get(org) and b.get(org): if a[org] b[org]: score 0.15 else: score - 0.10 # 公司不同是强反证 return round(max(score, 0.0), 3) def scan_duplicates(rows: list, threshold: float 0.82) - list: 两两比较返回超过阈值的疑似重复对 pairs [] for i in range(len(rows)): for j in range(i 1, len(rows)): s similarity(rows[i], rows[j]) if s threshold: pairs.append({a: rows[i][id], b: rows[j][id], score: s}) pairs.sort(keylambda x: -x[score]) return pairsthreshold定在 0.82 是我在几百条模拟数据上试出来的号码一致加姓名一致就是 0.85能进只有号码一致是 0.6进不来避免把公司前台电话相同的一堆人全判成重复姓名拼音一致加公司一致是 0.30也进不来。这个阈值放在config.py里演示时调低到 0.6界面立刻刷出一堆疑似重复观感很直观。真正让合并功能站得住的是回滚。执行合并时先把被合并记录的完整字段序列化成 JSON 写进merge_log再把标签和交互记录迁移到保留的那条上最后软删除被合并的记录。误合并之后从日志里读回 JSON 重建一条记录标签关联也一并恢复。没有这一步去重功能在答辩现场就是个定时炸弹——评委只要问一句“合并错了怎么办”没准备的人当场卡住。批量扫描的复杂度是 O(n²)一万条记录就是五千万次比较纯 Python 跑起来要几十秒。优化办法是先按手机号分组只对号码相同或姓氏拼音相同的记录两两比较候选集能压到很小。这个优化写进文档的“性能分析”章节是很实在的一笔。5. 避坑与排查这套毕设最容易翻车的五个点5.1 多音字姓名搜不到现象搜“单老师”搜不出来联系人明明叫“单磊”搜“曾”也找不到姓曾的人。原因lazy_pinyin默认取最常见读音“单”被转成dan而不是姓氏读音shan“曾”被转成zeng而人名里常读ceng“解”“查”“仇”同理。检索按拼音字段匹配读音错了自然搜不到。解决维护一张小规模姓氏多音字表在build_pinyin里对首字做特判同时把多种读音都写进检索字段。我的做法是给name_pinyin存主读音另加一个name_pinyin_alt存备选读音检索时两个字段都参与匹配。表不用大覆盖二三十个常见多音姓氏就够写进文档还能当“细节处理”讲。5.2 Excel 导入后手机号面目全非现象导入的号码变成1.38001E10或者开头的 0 消失了或者尾数变成 0。原因Excel 会把长数字自动识别成数值型超过 11 位就转科学计数法前导 0 被当成无意义的数字去掉。用openpyxl读取时如果不指定单元格类型拿到的就是浮点数。解决读取时强制按文本处理cell.value取到后统一转str遇到科学计数法格式的字符串做一次还原int(float(s))。更稳妥的做法是在导入说明里要求用户先把该列设为文本格式代码里再兜一层。这个坑我在两个项目里都遇到过属于不看就必踩的类型。5.3 并发写入报 database is locked现象前端快速点几下保存后端日志里冒出sqlite3.OperationalError: database is locked。原因SQLite 默认的写锁是独占的同一时刻只允许一个写事务。Flask 开发服务器默认多线程两个请求同时写就冲突默认等待超时只有几秒超时就抛错。解决连接时指定timeout15让写操作多等一会写入走统一的会话管理用完立即提交并关闭别让事务悬着。如果确实有并发压力把journal_mode切成 WAL读写可以并行。文档里写清“单机演示场景下的取舍”比硬上 Postgres 诚实得多。5.4 模糊匹配把搜索结果搅成一锅粥现象搜“张伟”列表里第一个是“张伟明”真正要的“张伟”排在第五个搜两个字的名字返回的全是备注里提到这两个字的无关记录。原因fuzz.partial_ratio对短串天然友好“张伟”是“张伟明”的子串得分直接 100。备注字段没有限制权重备注里提一嘴的名字也参与了打分。解决区分字段权重姓名和拼音的匹配权重远高于备注短查询词两个字及以下优先走前缀匹配而不是子串匹配排序时加一个“长度差惩罚”长度差越大扣分越多。这三个调整加完排序基本就正常了。5.5 演示数据太干净现场导入真实文件就崩现象自己准备的 CSV 跑得好好的答辩时导师随手从手机导出一份通讯录丢过来程序直接报编码错误或者字段错位。原因真实导出的文件编码可能是 GBK 或带 BOM 的 UTF-8字段顺序和列名也和你预设的不一样还可能有合并单元格和空行。解决导入函数不要写死编码按utf-8-sig、utf-8、gbk的顺序逐个尝试全失败再报错列名做模糊映射比如“电话”“手机”“手机号”“联系方式”都映射到phone空行和缺少姓名的行直接跳过并记录到导入报告里。答辩前自己找两三份不同来源的文件跑一遍这半小时能省掉现场十分钟的尴尬。6. 验收与答辩把一份能跑的代码讲成一套能过的设计验收这一步很多人以为是最后写个“测试结论”就完事其实验收清单应该在做功能的时候同步写。我的习惯是每个模块做完立刻补三条用例正常输入、边界输入、异常输入。等到答辩前一周这些用例直接拼成验收表比临时补要省太多时间。验收项验收方法通过标准联系人增删改查手工操作加接口调用各一遍回收站可还原软删除不丢数据CSV 导入准备 UTF-8、GBK、带 BOM 三份文件三份都能导入字段映射正确拼音检索搜全拼、首字母、错别字各三次目标联系人均在前三条去重扫描造十组已知重复混入非重复召回不低于八组误报不超过一组意图识别准备二十条高频指令命中不低于十五条未命中降级不报错性能导入五千条后测列表与检索列表响应一秒内检索两秒内这张表在答辩时的用法是不要念直接投在屏幕上挑一行讲你测出过什么问题、怎么改的。“去重扫描误报了一组”这种坦诚比宣称“全部通过”更让人信服。答辩讲解的顺序我建议倒着来先演示一个具体场景——打开系统导入一份乱糟糟的 CSV搜“zw”找到张伟说一句“帮我找上周联系过的客户”列表刷出结果。三分钟演完评委会自己产生“这东西能干什么”的判断你再回头讲架构和数据表他们听得进去。反过来先讲三层架构讲到第二层就开始走神了。有个容易被忽略的加分点主动交代边界。讲完功能花一分钟说明哪些没做、为什么不做——不抓取真实社交平台数据是合规考虑不微调大模型是算力考虑不做人脸匹配是样本量考虑。这段话的作用是把“没做完”转化成“想清楚了”差别很大。还有一点源代码和开发文档说明要保持同步。我见过太多人代码改到最后一版文档还停在两周前字段名对不上、接口路径不一致评委翻两页就发现问题。我的做法是每次改动数据库字段或接口先改文档里的表再改代码顺序反了就会忘。从那以后我每次交方案前都会强制走一遍“换台电脑”流程清空环境只按文档里的步骤装依赖、初始化数据库、导入示例数据、跑一遍演示脚本。凡是文档里没写清、导致这一步卡住的地方全部当成 bug 修文档。这个习惯救过我至少两次其中一次是发现初始化脚本漏了创建索引五千条数据下检索慢了十倍自己机器上有旧库所以一直没暴露。希望这套结构能帮到你把手里那份代码讲成一份像样的方案。本文还有配套的精品资源点击获取
