當程式碼審查需要的內容不只 diff 時，請透過 Novita AI API 使用 MiniMax M3。本教學將說明如何封裝功能簡介、選定的原始碼檔案、測試輸出及儲存庫筆記，發送給 minimax/minimax-m3，並將回應轉換為維護人員在合併前可以實際核對的審查發現。
重點摘要
- 當審查需要廣泛的程式碼上下文、測試輸出、影像輸入（如螢幕截圖）或結構化輸出時，MiniMax M3 是一個不錯的選擇。
- Novita AI API 使用兼容 OpenAI 的基礎 URL，因此現有的聊天完成客戶端程式碼很容易調整。
- 保持 AI 審查評論有據可查。如果某項發現無法追溯到程式碼、測試、日誌或需求，請勿將其作為事實發布。
什麼是長上下文程式碼審查 API 工作流程？
長上下文程式碼審查 API 會將 Pull Request 中各個部分（審查人員通常會在不同分頁中保持開啟的內容）發送給模型：變更摘要、相關檔案、差異、失敗的測試、日誌、架構說明和審查規則。然後模型會返回可能的風險、建議的修正以及給維護人員的問題。
這不會取代測試或人工審查。它有助於解決煩人的部分：在腦中維持足夠的上下文。Linters 和靜態分析工具擅長於逐行的檢查，但在發現依賴於遠端模組、舊遷移、功能標誌或部署設定的行為時，它們的表現就差得多了。
MiniMax M3 適合這項工作，因為 Novita AI 將其列為具有 1,000,000 個 token 的上下文視窗、131,072 個 token 的最大輸出、無伺服器存取以及面向程式碼的能力。這對於真實的 Pull Request 很重要，因為其中有用的上下文可能包含原始程式碼、測試輸出、螢幕截圖和簡短的產品簡介。
何時使用 Novita AI API 進行程式碼審查
當程式碼審查需要成為可重複流程的一部分時，請使用 Novita AI API：CI、Pull Request 機器人、發布檢查清單或內部開發者工具。對於臨時性的幫助，一次性聊天提示就足夠了。當輸入格式、輸出結構、日誌、成本追蹤和降級行為需要保持一致時，API 呼叫是更好的選擇。
此模式適用於以下情況：
- 觸及多個服務或套件的大型 Pull Request。
- 需要同時考量 Schema、API、配置和測試的遷移審查。
- 安全性敏感變更，需要對不安全的輸入處理、授權漏洞或機密暴露進行二次檢查。
- UI 變更，其中原始檔案和螢幕截圖都很重要，而最終答案應保持為文字。
- 需要在實作代理提出補丁後進行驗證步驟的自主編碼系統。
不要將 AI 審查用於靜態分析已能妥善處理的工作。格式化、未使用的 imports、依賴授權掃描和已知漏洞檢查應保持確定性。將模型放在這些工具之上一個層級，用於回答更接近「當我閱讀整個系統時，這個變更還有意義嗎？」這類問題。
選擇正確的 Novita AI 模型或 API 路徑
當審查需要全面了解變更時，從 MiniMax M3 開始。對於短暫的單一檔案檢查，請使用較小的模型或完全跳過 AI 步驟。
| 選項 | 最佳用途 | 為什麼選擇 | 注意事項 |
|---|---|---|---|
minimax/minimax-m3 |
大型程式碼庫審查、遷移風險分析、代理驗證器檢查 | 長上下文、大輸出、多模態輸入、函數呼叫、結構化輸出和無伺服器存取 | 對於短暫的單一檔案檢查來說太強大了 |
| Novita 兼容 OpenAI 的聊天完成 | 已在使用 OpenAI SDK 請求模式的應用程式 | 通常只需更改 base URL 和 model ID 即可調整現有客戶端程式碼 | 在推出前檢查模型限制、定價和支援的功能 |
| 靜態分析器和測試套件 | 樣式、型別、安全性和回歸檢查 | 快速、可重複、易於在 CI 中設門檻 | 它們不善於解釋跨檔案的產品風險或歧義意圖 |
本教學中最有用的版本是遷移風險審查：一個請求包含功能簡介、變更的檔案、相關未變更的檔案、相關測試輸出和審查規則。MiniMax M3 的長上下文讓您可以保留更多這些素材，而不是將它們塞進模糊的摘要中。
步驟 1：定義程式碼審查輸入和輸出格式
在呼叫 API 之前，決定模型允許審查的內容以及您希望得到的答案類型。一個有用的請求通常包含五個部分。
首先，包含一個簡短的變更簡介。解釋目標、受影響的功能、預期行為以及任何不能改變的事項。模型應知道它是在審查重構、新的 API 端點、資料庫遷移、依賴升級還是 UI 行為變更。
其次，包含 diff 和選定的完整檔案。Diff 顯示了變更的內容。完整檔案顯示了慣例、幫助函數、驗證模式和現有的邊界情況。對於大型儲存庫，應包含已變更的檔案、被變更檔案匯入的檔案，以及在測試或日誌中提及的檔案。
第三，添加機器輸出：失敗的測試、相關通過測試的名稱、linter 輸出、API 合約片段、資料庫結構變更或部署配置。嚴格修剪終端機日誌。模型不需要 600 行的安裝噪音。
第四，包含審查規則。告訴模型什麼是重要的：正確性、安全性、資料遺失、相容性、效能、可觀測性、推出安全性或文件偏離。也要說明什麼可以忽略，例如由其他工具處理的格式化。
第五，要求結構化輸出。Novita 的聊天完成 API 支援使用 JSON schema 的 response_format，而 MiniMax M3 被列為支援結構化輸出。這使得結果更容易解析、去重，並轉換為 Pull Request 評論。
這是一個合理的初始 schema：
{
"summary": "一段摘要的審查總結。",
"risk_level": "low | medium | high",
"findings": [
{
"severity": "blocker | high | medium | low",
"title": "簡短的發現標題",
"evidence": "檔案、函數、測試或日誌證據",
"impact": "可能出錯的影響",
"recommendation": "具體的修正或驗證步驟",
"confidence": "high | medium | low"
}
],
"needs_human_review": [
"需要維護人員處理的具體問題或假設"
]
}
步驟 2：配置 Novita AI API 請求
Novita AI 提供一個兼容 OpenAI 的聊天完成端點。將用戶端 base URL 設為 https://api.novita.ai/openai，使用 /v1/chat/completions，並將您的 API 金鑰作為 bearer token 發送。
在環境變數中設定 API 金鑰：
export NOVITA_API_KEY="your_api_key_here"
如果您的專案尚未包含 OpenAI Python SDK，請安裝它：
pip install openai
然後使用 Novita 的 base URL 配置客戶端：
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["NOVITA_API_KEY"],
base_url="https://api.novita.ai/openai",
)
使用 minimax/minimax-m3 作為模型 ID。在日誌中記錄模型 ID、提示版本、原始碼 commit、包含的檔案、token 使用量和驗證狀態。這些細節在審查評論錯誤之前可能很無聊，但屆時正是您所需要的。
步驟 3：調整程式碼審查 API 請求
下面的範例是一個起手模式，不是可以直接投入使用的 CI 機器人。替換範例中的 review_packet，用您自己的 Novita API 金鑰進行測試，並在將任何內容發布到 Pull Request 之前確認回應格式。
import json
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["NOVITA_API_KEY"],
base_url="https://api.novita.ai/openai",
)
review_packet = {
"change_brief": "Replace legacy user import job with streaming CSV parser.",
"review_goals": [
"Find correctness risks",
"Find data-loss risks",
"Check migration and rollback safety",
"Ignore formatting-only comments"
],
"diff": """
diff --git a/jobs/import_users.py b/jobs/import_users.py
...
""",
"related_files": {
"jobs/import_users.py": "def import_users(...): ...",
"models/user.py": "class User(...): ...",
"tests/test_import_users.py": "def test_duplicate_email_rows(...): ..."
},
"test_output": "2 failed, 41 passed. Failure: duplicate email row overwrites existing active user.",
}
schema = {
"type": "object",
"additionalProperties": False,
"properties": {
"summary": {"type": "string"},
"risk_level": {"type": "string", "enum": ["low", "medium", "high"]},
"findings": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": False,
"properties": {
"severity": {
"type": "string",
"enum": ["blocker", "high", "medium", "low"]
},
"title": {"type": "string"},
"evidence": {"type": "string"},
"impact": {"type": "string"},
"recommendation": {"type": "string"},
"confidence": {
"type": "string",
"enum": ["high", "medium", "low"]
}
},
"required": [
"severity",
"title",
"evidence",
"impact",
"recommendation",
"confidence"
]
}
},
"needs_human_review": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["summary", "risk_level", "findings", "needs_human_review"]
}
response = client.chat.completions.create(
model="minimax/minimax-m3",
messages=[
{
"role": "system",
"content": (
"You are a senior code reviewer. Return only findings that are "
"supported by the supplied evidence. Do not invent files, tests, "
"logs, requirements, or line numbers."
),
},
{
"role": "user",
"content": json.dumps(review_packet),
},
],
max_tokens=4096,
temperature=0.1,
response_format={
"type": "json_schema",
"json_schema": {
"name": "code_review_result",
"schema": schema,
"strict": True,
},
},
)
result = json.loads(response.choices[0].message.content)
print(json.dumps(result, indent=2))
print(response.usage)
保持 max_tokens 足夠大以獲得有用的發現，同時小到足以避免輸出過多頁面。Novita 的聊天完成參考要求 max_tokens，且提示加上輸出必須符合模型上下文。如果請求太大，Novita 可能會降低 max_tokens 以符合限制。這可以防止某些嚴重失敗，但您的應用程式仍應追蹤提示大小，以便在重要的審查上下文被擠壓時發出警告。
步驟 4：驗證並改進程式碼審查結果
不要因為 AI 審查說看起來安全就合併程式碼。將回應視為一位有時會過度解讀的敏銳審查者。
從 schema 開始。如果回應不符合，使用相同的輸入和更嚴格的系統指令重試一次。如果仍然失敗，將 AI 審查標記為無結論，而不是發布格式錯誤的評論。
然後檢查證據。每項發現都應指向請求中的檔案、函數、測試、日誌行或需求。刪除任何無法與提供的上下文關聯的內容。根據受影響的元件和使用者影響對重複項目進行分組。先顯示重要的項目。
這是一個簡單的後處理模式：
def filter_supported_findings(result):
supported = []
for finding in result["findings"]:
evidence = finding["evidence"].lower()
has_file_or_test = any(
marker in evidence
for marker in [".py", ".ts", ".go", ".java", "test", "log", "migration"]
)
if has_file_or_test and finding["confidence"] != "low":
supported.append(finding)
return supported
supported_findings = filter_supported_findings(result)
對於真實系統，請將該簡單過濾器替換為能感知儲存庫的驗證。檢查引用的路徑是否存在於 Pull Request 中、測試名稱是否出現在測試輸出中，以及發現是否指向已變更的行或相關的依賴。
步驟 5：為生產環境準備程式碼審查工作流程
生產環境的審查機器人需要在成本、隱私、可靠性和信任方面設置護欄。
關於成本，請從即時的 Novita 模型列表和您的帳戶儀表板開始。不要在機器人中硬編碼 token 價格。從每個回應記錄 token 使用量，在推出前檢查當前的 MiniMax M3 定價，並針對實際 Pull Request 量設置警報。
關於隱私，嚴格限制進入請求的內容。不要發送機密、私鑰、客戶資料或生產憑證。在 API 呼叫之前執行機密掃描，並對日誌進行脫敏。如果審查需要機密檔案，請先檢查您的內部資料政策。
關於可靠性，決定 API 呼叫失敗時的處理方式。一個合理的預設值是：「AI 審查不可用；確定性檢查仍已執行。」除非團隊明確選擇了該取捨，否則不要讓整個 Pull Request 因短暫的 AI 中斷而阻塞。
關於審查者的信任，少發佈。一個包含 30 條推測性評論的 Pull Request 評論會被忽略。發布高信心的發現，將其與相關檔案或測試關聯，並包含模型 ID 和提示版本以便審計。
首先以觀察模式推出。運行 AI 審查但不發布評論，將其發現與人工審查結果進行比較，並追蹤真陽性和假陽性。只有這樣才應啟用 Pull Request 評論。阻斷行為應該罕見且範圍狹窄，例如確認的機密暴露或遷移回滾缺口。
AI 程式碼審查檢查清單
- 請求包含變更簡介、diff、選定的完整檔案、相關測試和審查規則。
- 回應符合您的 JSON schema。
- 發現引用提供的上下文，而非虛構的檔案、測試或行號。
- 每個發現都有嚴重性、證據、影響、建議和信心等級。
- 日誌記錄模型 ID、提示版本、原始碼 commit、包含的檔案、token 使用量和驗證狀態。
- Pull Request 機器人隱藏低信心或重複的評論。
- 在推出前檢查當前的定價、模型限制和可用性。
Novita AI API 工作流程疑難排解
| 問題 | 可能的原因 | 修正方法 |
|---|---|---|
| API 返回驗證錯誤 | Bearer token 缺失或格式錯誤 | 確認已設定 NOVITA_API_KEY，並作為 Authorization: Bearer ... 發送 |
| 回應是有效文字但不是有效 JSON | 未強制執行 schema，或模型未獲得明確的輸出契約 | 使用帶有 json_schema 的 response_format，保持 schema 簡潔，並重試一次 |
| 審查遺漏了一個明顯的問題 | 請求中未包含證明該問題的檔案、測試或需求 | 包含已變更的檔案、直接 imports、失敗的測試和遷移檔案 |
| 審查引用了不存在的證據 | 提示允許猜測，或後處理器未檢查引用 | 僅要求提供的上下文，並刪除無法映射到請求檔案或日誌的發現 |
| Pull Request 評論太長 | Schema 允許過多發現 | 在發布前根據嚴重性和信心等級對發現進行上限 |
| 成本快速攀升 | 大型 diff、重複重試或高 max_tokens 值 |
測量 token 使用量，設定重試上限，並總結低價值檔案 |
| 延遲過高 | 請求包含的上下文比審查所需的更多 | 按元件拆分檢查，或將長上下文審查保留給大型或風險高的變更 |
常見問題
對於長上下文程式碼審查，我應該使用哪個 Novita AI 模型？
當審查需要廣泛的程式碼上下文、測試輸出、影像輸入（如螢幕截圖）或結構化輸出時，使用 minimax/minimax-m3。Novita 將 MiniMax M3 列為無伺服器聊天模型，具有 1,000,000 token 的上下文視窗和 131,072 的最大輸出 token。對於較短的檢查，考慮測試一個較小的模型，並根據您自己的工作負載比較成本、延遲和品質。
我可以在 Novita AI API 工作流程中稍後切換模型嗎？
可以，只要替換的模型支援您依賴的端點模式和功能。在切換之前，請檢查模型 ID、上下文長度、最大輸出、模態支援、結構化輸出支援、工具支援、定價以及您自己審查集上的輸出品質。
如何使用 Novita AI API 估算程式碼審查成本？
使用即時的 Novita 定價和您自己的 token 測量。對於每次運行，記錄提示 token、生成 token、重試次數以及是否使用了快取上下文。在您設定預算或將機器人設為阻斷性 CI 步驟之前，將該使用量與當前的 MiniMax M3 定價進行比較。
哪些輸入最適合 AI 程式碼審查？
最佳的輸入是具體的：變更簡介、diff、選定的完整檔案、測試輸出、相關日誌、schema 或 API 合約，以及審查規則。避免預設傾倒整個儲存庫。長上下文有幫助，但不相關的上下文會使審查變慢且噪音更大。
AI 程式碼審查的主要生產風險是什麼？
主要風險是虛假信心、無根據的發現、遺漏問題、敏感資料暴露、成本漂移和審查者疲勞。透過 schema 驗證、證據檢查、機密掃描、token 監控、人工審查和保守的 Pull Request 評論來降低這些風險。
