簡介面向麻將游戲自動化與圖像識別開發(fā)者的實(shí)用AI SDK資源包聚焦牌面識別、策略決策與自動打牌場景適合對棋牌AI、計算機(jī)視覺感興趣的入門及進(jìn)階開發(fā)者使用。壓縮包共29個文件約8.74MB包含8個Python腳本、12張圖像、2個說明文檔以及proto、pkl、model、json、license、md等類型分別對應(yīng)核心調(diào)用邏輯、界面/牌面素材、項(xiàng)目介紹與協(xié)議說明結(jié)構(gòu)清晰便于二次開發(fā)。已有314人學(xué)習(xí)瀏覽。SDK提供封裝好的Python接口與預(yù)訓(xùn)練模型可直接接入麻將AI平臺借助圖像識別完成牌面檢測并觸發(fā)自動化打牌動作說明文檔、模型文件和配置文件覆蓋環(huán)境準(zhǔn)備、接口調(diào)用與策略調(diào)參等環(huán)節(jié)既適合快速跑通Demo也能作為獨(dú)立項(xiàng)目起步模板或技術(shù)驗(yàn)證工具方便開發(fā)者進(jìn)一步擴(kuò)展牌型識別、出牌決策等功能。1. 項(xiàng)目緣起為什么我會把麻將、圖像識別、AI和SDK放在同一個壓縮包里先說清楚這個zip壓縮包不是什么黑科技成品而是我自己花了兩周時間折騰的一套“麻將圖像識別與自動化打牌實(shí)驗(yàn)系統(tǒng)”的源碼、模型和文檔合集。文件名里的時間戳1743961947是我最后一次打包上傳的時間。核心解決的事情很簡單當(dāng)電腦屏幕上有一局麻將進(jìn)行時程序能通過圖像識別看清牌面調(diào)用本地推理SDK做決策再模擬鼠標(biāo)操作完成打牌動作。先說一個老實(shí)話這套東西的工程意義遠(yuǎn)大于實(shí)際使用意義。麻將識別本身是計算機(jī)視覺里一個非常經(jīng)典的細(xì)分場景——目標(biāo)小、紋理復(fù)雜、牌面相似度高而且不同平臺、不同分辨率的麻將素材差異極大。搞懂這條路你能遷移到棋牌AI、工業(yè)質(zhì)檢、票據(jù)識別好多領(lǐng)域。至于自動化打牌我個人建議只在研究環(huán)境或自己搭的測試平臺里跑合規(guī)風(fēng)險自己掂量。適合來看這篇內(nèi)容的人我概括成三類一是想做圖像識別入門到進(jìn)階的開發(fā)者二是對AI Agent調(diào)用SDK落地流程感興趣的人三是純粹對“視覺決策控制”這套完整閉環(huán)好奇的玩家。你不需要懂麻將規(guī)則但至少會Python、用過OpenCV讀起來會舒服很多。2. 整體架構(gòu)與方案選型先畫閉環(huán)再談代碼2.1 系統(tǒng)閉環(huán)拆解看得見、想得清、做得出整套系統(tǒng)拆成三個環(huán)節(jié)視覺感知、決策大腦、動作執(zhí)行。視覺感知負(fù)責(zé)從屏幕畫面里把每張麻將牌識別出來輸出結(jié)構(gòu)化信息比如“手牌有1萬、5筒、紅中牌河區(qū)域有人打過3條”。這部分的核心指標(biāo)是準(zhǔn)確率和幀率——你要做到每幀200毫秒內(nèi)完成一整桌牌的識別否則決策模塊拿到的是過期數(shù)據(jù)等于瞎打。決策大腦接收當(dāng)前局面輸出“該出哪張牌”或“該碰/杠/吃”。傳統(tǒng)做法是規(guī)則引擎比如判斷聽牌、計算向聽數(shù)、評估安全度?，F(xiàn)代做法是模型推理小模型跑本地大模型走API。我這次用的方案是混合架構(gòu)規(guī)則做兜底模型做加分。動作執(zhí)行是把決策轉(zhuǎn)化為鼠標(biāo)操作定位到要操作的牌點(diǎn)擊、拖動、確認(rèn)。這個環(huán)節(jié)看起來簡單實(shí)際最容易被忽略因?yàn)槠聊蛔鴺?biāo)映射、點(diǎn)擊延遲、操作間隔都會直接影響成功率。2.2 技術(shù)棧選型為什么是OpenCV YOLOv8 ONNX Runtime選型這件事我是踩過不少坑之后才定下來的這里直接給結(jié)論。視覺部分用OpenCV做預(yù)處理配合YOLOv8做牌面檢測。為什么不直接用Tesseract OCR因?yàn)槁閷⑹菆D案文字的混合體普通OCR對花牌、字牌東南西北中發(fā)白的識別率慘不忍睹而且沒有牌面定位能力。YOLOv8這類目標(biāo)檢測模型可以直接給出“牌面bounding box 類別”一步到位。訓(xùn)練平臺上我用了自己手頭的一張2080 Ti數(shù)據(jù)集是自己截圖網(wǎng)上公開的麻將圖片混合標(biāo)注的總共訓(xùn)了大概4000張圖。說實(shí)話數(shù)據(jù)質(zhì)量比數(shù)量重要得多——我一開始為了湊數(shù)拉了一堆低分辨率圖進(jìn)來結(jié)果mAP反而掉了兩個點(diǎn)。推理端我用ONNX Runtime導(dǎo)出部署因?yàn)闆Q策模塊需要低延遲直接用PyTorch的Python接口在Windows上做實(shí)時推理啟動速度和內(nèi)存占用都不好看。ONNX Runtime在CPU上也跑得動這一點(diǎn)對沒有獨(dú)顯的測試機(jī)很友好。決策模塊的AI SDK調(diào)用我封裝了一個獨(dú)立的Python包支持兩種后端一種是本地規(guī)則引擎速度快、可解釋性強(qiáng)另一種是調(diào)用本地部署的大模型API接口語言理解強(qiáng)但延遲高、穩(wěn)定性依賴網(wǎng)絡(luò)。兩套后端通過統(tǒng)一接口切換這個設(shè)計后續(xù)幫我省了不少測試時間。3. 視覺模塊實(shí)戰(zhàn)讓程序“看清”麻將的每一步3.1 圖像采集與預(yù)處理屏幕抓幀的穩(wěn)定性是第一道坎圖像采集我用的是mss庫截取屏幕區(qū)域。這個庫比PIL的ImageGrab快很多速度基本在30ms左右截一幀而且支持指定區(qū)域不用每次截全屏。我直接硬編碼配置了測試平臺的窗口位置、分辨率和一個縮放比例實(shí)測下來mss的穩(wěn)定性是夠用的。預(yù)處理流程看起來常規(guī)但細(xì)節(jié)決定成敗。第一件事是摳出桌面區(qū)域用背景建?；蚬潭０宥急热珗D處理省下大量算力。我用的方法是第一次運(yùn)行截一張空桌面圖做背景之后每幀和背景做差分變化區(qū)域就是牌桌。這個方法在環(huán)境不變的情況下效果很好但如果窗口移動位置就會出問題所以我最終換成了固定坐標(biāo)區(qū)域截取。第二件事是轉(zhuǎn)灰度、做直方圖均衡。麻將在不同光線下明暗差異很大均衡之后能顯著提升后續(xù)檢測的穩(wěn)定性。這一步效果在暗色背景的牌桌上特別明顯。第三件事是尺寸歸一化。我按牌面最小寬度的兩倍做檢測輸入尺寸保證YOLO輸入清晰度足夠。注意不要暴力拉伸會改變牌的寬高比導(dǎo)致邊界框漂移。我踩過這個坑后來改成按長邊等比縮放并填充黑邊識別效果立刻上去一截。3.2 牌面定位與識別YOLOv8檢測 特征分類的組合拳模型選型這里我詳細(xì)說說為什么是“YOLOv8做檢測 輕量CNN做分類”兩個階段。第一階段YOLOv8只負(fù)責(zé)找牌和切牌類別就兩類“hand牌”手牌區(qū)和“discard牌”牌河區(qū)。為什么不在這一步直接分34類因?yàn)榕泼骖悇e太多而且手牌和牌河的姿態(tài)、遮擋、角度都有差異一步到位對訓(xùn)練數(shù)據(jù)要求極高。拆成兩步每步都簡單效果反而更穩(wěn)。第二階段把每張牌從原圖上摳出來縮放到128x128送進(jìn)一個MobileNetV3做34分類。這一步的訓(xùn)練數(shù)據(jù)完全來自第一階段的檢測結(jié)果裁剪圖相當(dāng)于自己生成數(shù)據(jù)集省去了手動標(biāo)注的大量時間。兩階段推理的平均時間在50ms左右完全滿足實(shí)時要求。檢測分類準(zhǔn)確率實(shí)測在96%以上。剩下4%的誤差主要來自暗光下對“索子”和“條子”的混淆以及某些花牌的相似紋理。這里給一個關(guān)鍵參數(shù)建議YOLO的檢測置信度閾值設(shè)0.4NMS的IoU閾值設(shè)0.5偏低是故意的因?yàn)閷幙啥鄼z測出候選框讓第二階段去false positive過濾。分類階段的置信度閾值設(shè)0.9以上過濾掉模糊樣本寧可漏檢也不誤檢。3.3 視頻流與幀率取舍為什么我只做單幀識別不追幀很多人可能覺得視頻識別比圖像識別高端但在這個場景里單幀識別是更聰明的選擇。麻將牌的移動是瞬時的沒有連續(xù)運(yùn)動的規(guī)律可循追幀反而容易引入重影和中間幀模糊。所以我在截屏線程里直接做了間隔采樣每200毫秒截一幀做完整識別然后緩存最近三幀結(jié)果用投票法決定最終狀態(tài)。這樣既避免了單幀偶發(fā)錯誤又不需要做真正的視頻流解碼。給大家一個參考用mss截屏兩個階段推理整體CPU占用約35%GPU顯存占用2GB左右低配機(jī)器也能跑。4. AI決策模塊從規(guī)則引擎到SDK調(diào)用的架構(gòu)演進(jìn)4.1 規(guī)則引擎兜底向聽數(shù)計算和基礎(chǔ)出牌策略決策模塊最核心的算法是向聽數(shù)計算。向聽數(shù)就是“距離聽牌還有幾張有效牌”0向聽就是已經(jīng)聽牌1向聽就是再進(jìn)一張有效牌就聽牌。計算向聽數(shù)是個經(jīng)典回溯算法對14張手牌做拆分鬼牌癩子可以當(dāng)作任意牌處理。我基于向聽數(shù)寫了三層決策邏輯如果當(dāng)前出牌會讓向聽數(shù)增加優(yōu)先選維持向聽數(shù)的牌如果有多張牌都能維持向聽數(shù)按“安全度”排序優(yōu)先打熟張如果已經(jīng)0向聽就按聽牌的張數(shù)最大化原則選擇。這套規(guī)則引擎響應(yīng)時間在1ms以內(nèi)作為兜底完全夠用。但規(guī)則引擎有個死穴——處理不了復(fù)雜局面。比如對手明顯在做大牌你是否該拆自己的好牌去防守這種博弈層面的問題規(guī)則寫起來無窮無盡。所以我在規(guī)則引擎之上加了一層模型。4.2 調(diào)用AI SDK做決策增強(qiáng)本地模型和大模型API雙通道決策增強(qiáng)的SDK封裝我實(shí)現(xiàn)了兩個后端本地模型后端用PyTorch訓(xùn)練了一個小型的策略網(wǎng)絡(luò)輸入是“手牌編碼 牌河編碼 對手動作歷史”輸出是34維的出牌概率分布。訓(xùn)練數(shù)據(jù)是從大量對局記錄里提取的用self-play做了強(qiáng)化學(xué)習(xí)的迭代優(yōu)化。這個網(wǎng)絡(luò)很小參數(shù)量只有幾百萬CPU推理大約20ms。大模型API后端把局面編碼成文本提示詞請求本地部署的Qwen大模型接口讓大模型給出出牌建議及理由。效果上大模型對大局觀的理解明顯更強(qiáng)但延遲在1-2秒級別不適合實(shí)時決策我只在測試模式里用它分析歷史牌局。SDK的統(tǒng)一接口長這樣class MahjongDecisionSDK: def get_action(self, state_dict): ...傳入一個state_dict返回一個動作字典。至于內(nèi)部走規(guī)則引擎、本地模型還是大模型API由配置切換。這套抽象讓我在后續(xù)測試中對比不同決策策略時省了大力氣。4.3 SDK調(diào)用鏈路的錯誤處理與降級策略實(shí)際調(diào)用AI SDK時我最擔(dān)心的是API服務(wù)不可用。我在SDK里加了三層降級先走本地模型如果本地模型加載失敗比如顯存不足降級到規(guī)則引擎如果大模型API連接超時也降級到規(guī)則引擎。這么設(shè)計之后系統(tǒng)可以在任何情況下都能給出一個可用的動作哪怕它不夠聰明至少不會因?yàn)闆Q策模塊崩潰導(dǎo)致整個程序退出。5. 動作執(zhí)行模塊把決策變成真實(shí)的鼠標(biāo)點(diǎn)擊5.1 屏幕坐標(biāo)映射的兩種方案對比決策模塊輸出的是邏輯動作比如“打掉手牌索引為3的1萬”動作執(zhí)行模塊必須把它映射成屏幕上的實(shí)際點(diǎn)擊坐標(biāo)。我在測試中試過兩種方案絕對坐標(biāo)映射基于截屏區(qū)域的坐標(biāo)和實(shí)際屏幕坐標(biāo)的線性關(guān)系直接換算。前提是牌桌位置固定窗口不可移動。相對位置映射檢測手牌區(qū)域的bounding box在手牌區(qū)域內(nèi)等距劃分位置。優(yōu)勢是窗口移動也能自適應(yīng)劣勢是當(dāng)牌數(shù)變化比如剛摸牌、剛出牌時牌間距不均映射誤差會變大。我最終用的是“絕對坐標(biāo)為主動態(tài)修正為輔”啟動時用一張已知牌面做校準(zhǔn)計算出準(zhǔn)確坐標(biāo)偏移量運(yùn)行中每幀識別牌的位置動態(tài)修正點(diǎn)擊目標(biāo)。5.2 鼠標(biāo)操作的穩(wěn)健實(shí)現(xiàn)間隔、漂移與異?；謴?fù)模擬鼠標(biāo)操作我用pyautogui庫。有兩個關(guān)鍵點(diǎn)操作間隔必須有隨機(jī)性。如果固定間隔點(diǎn)擊很容易被環(huán)境識別為腳本操作。我把每次點(diǎn)擊間隔設(shè)在0.3到0.6秒之間隨機(jī)分布移動軌跡也用隨機(jī)貝塞爾曲線模擬。這不是為了作弊是為了讓自動化流程更接近真實(shí)操作節(jié)奏避免誤觸校驗(yàn)。此外我加了一個異常恢復(fù)機(jī)制點(diǎn)擊之后會立即重新截屏識別一次判斷這步操作是否真的生效。如果沒生效重試最多三次三次還不行就暫停并輸出告警日志。這個機(jī)制在識別精度不夠高時尤其重要能在出錯時及時止損。6. 常見問題與調(diào)試實(shí)錄那些讓我深夜崩潰的坑6.1 牌面識別總是把“6筒”看成“8筒”怎么排查這個坑我印象太深了。排查步驟先分階段測試把YOLO檢測輸出可視化發(fā)現(xiàn)裁剪出來的牌面區(qū)域本身沒被截歪問題出在分類器上。我又把分類器的中間特征圖可視化發(fā)現(xiàn)6筒和8筒在淺層特征上確實(shí)高度相似。最終定位到原因是訓(xùn)練數(shù)據(jù)里這兩個類別樣本不均衡6筒樣本比8筒多了三倍。我用數(shù)據(jù)增強(qiáng)旋轉(zhuǎn)、縮放、亮度擾動把8筒補(bǔ)到差不多數(shù)量mAP直接回升了3個百分點(diǎn)。經(jīng)驗(yàn)是出現(xiàn)細(xì)分類別混淆第一反應(yīng)不是調(diào)模型結(jié)構(gòu)而是檢查數(shù)據(jù)分布是否均衡。很多分類問題90%出在數(shù)據(jù)上不是模型不行。6.2 自動化操作偶發(fā)無效怎么定位是識別錯了還是點(diǎn)擊錯了這個問題的排查思路是分層隔離。我在執(zhí)行鏈路的每個環(huán)節(jié)都加了日志識別結(jié)果、決策結(jié)果、映射坐標(biāo)、點(diǎn)擊動作、執(zhí)行后識別結(jié)果。那次排查發(fā)現(xiàn)識別結(jié)果和決策結(jié)果都正確映射坐標(biāo)略偏——原來是系統(tǒng)顯示縮放比例改成了125%坐標(biāo)換算基數(shù)沒同步更新。這個坑提醒我坐標(biāo)映射代碼里凡是涉及屏幕分辨率的常量都要從系統(tǒng)設(shè)置中動態(tài)讀取不能寫死。6.3 SDK調(diào)用頻繁超時如何優(yōu)化我踩過的一個真實(shí)案例是本地大模型API接口在處理長上下文時響應(yīng)時間超過了4秒而決策模塊的等待超時設(shè)置在3秒。這就導(dǎo)致每次決策都全部降級到規(guī)則引擎模型效果完全沒發(fā)揮出來。優(yōu)化方案是上下文裁剪只保留最近兩輪的動作記錄丟棄早期步驟把請求token控制在1200以內(nèi)響應(yīng)時間降到800ms。所以調(diào)用大模型API時一定要先分析你的瓶頸是在網(wǎng)絡(luò)、服務(wù)端推理還是上下文長度上對癥下藥而不是盲目加超時時間。7. 實(shí)測數(shù)據(jù)與合規(guī)提醒最后做個數(shù)據(jù)總結(jié)。整套系統(tǒng)在Windows 11 i5-12400F 16GB內(nèi)存的機(jī)器上單幀識別耗時約120ms決策耗時約80ms執(zhí)行耗時約400ms。整體從“屏幕畫面變化”到“鼠標(biāo)完成點(diǎn)擊”的響應(yīng)延遲約600ms接近真人打牌的節(jié)奏。模型指標(biāo)牌面檢測mAP 0.72分類準(zhǔn)確率96.4%決策模塊在2000局自對弈中勝率為57%。作為一個實(shí)驗(yàn)項(xiàng)目效果基本達(dá)到預(yù)期。但我要再次強(qiáng)調(diào)這套系統(tǒng)的開發(fā)初衷是學(xué)習(xí)圖像識別、目標(biāo)檢測、AI決策和SDK集成的完整鏈路不建議在真實(shí)在線麻將平臺上使用自動化功能。一方面這違反大多數(shù)游戲的服務(wù)條款另一方面用它去打牌贏錢毫無意義——技術(shù)樂趣和技術(shù)表達(dá)才是折騰這個項(xiàng)目的價值所在。個人學(xué)習(xí)請在本地或自建環(huán)境測試。如果你也想動手做一遍我的建議是先從“純圖像識別”入手把模型訓(xùn)練好識別率達(dá)到90%以上再考慮加入決策和自動化點(diǎn)擊。別一上來就貪多每一步都扎實(shí)了整個系統(tǒng)自然就立住了。本文還有配套的精品資源點(diǎn)擊獲取