在 iOS 应用中实现 OCR、人脸/条码检测…

为 iOS 应用添加端侧计算机视觉能力（文字识别、人脸检测、条码扫描、图像分割、目标跟踪、文档扫描、Core ML 模型推理）时，按现代/旧版 API 分层实现的完整做法。

适用场景

解决思路

1. 新代码优先使用 iOS 18+ 的现代 Swift 原生 API：创建请求类型后调用 `try await request.perform(on:)`，仅在部署目标要求时才加载旧版参考。
2. 将旧版 `VN*` 类型、`VNImageRequestHandler`、`VNSequenceRequestHandler`、completion handler 和旧版 `CGRect` 辅助方法隔离在明确的 legacy fallback 文件或代码段中。
3. 现代 API 遵循统一模式：创建请求（如 `var request = RecognizeTextRequest()`）、设置属性、调用 `perform(on:)`、处理强类型返回值。
4. OCR 使用 `RecognizeTextRequest`：设置 `recognitionLevel`（`.accurate` 用于静态图，`.fast` 用于实时）、`recognitionLanguages`（用 `Locale.Language(identifier:)`）、`usesLanguageCorrection`，并用 `customWords` 添加领域术语。
5. OCR 结果通过 `observation.topCandidates(1).first` 取 `string`、`confidence`（0.0–1.0）和 `boundingBox`（NormalizedRect）。
6. 人脸检测使用 `DetectFaceRectanglesRequest` 获取 `boundingBox`、`roll`、`yaw`；使用 `DetectFaceLandmarksRequest` 获取眼睛、鼻子、嘴部轮廓点。
7. 坐标转换：Vision 使用原点在左下角的归一化坐标系，显示前用 `rect.toImageCoordinates(imageSize, origin: .upperLeft)` 转成 UIKit 坐标（旧版用 `VNImageRectForNormalizedRect(_:_:_:)`）。
8. 条码检测使用 `DetectBarcodesRequest`，通过 `symbologies` 只指定需要的类型（如 `.qr`、`.ean13`、`.code128`、`.pdf417`），读取 `payloadString`、`symbology`、`boundingBox`；先对局部值做类型标注再单独赋值请求属性。
9. 文档扫描（iOS 26+）使用 `RecognizeDocumentsRequest`，从 `observation.document` 的 `Container` 中读取 `text`、`paragraphs`、`tables`、`lists`、`barcodes` 和 `title`；简单相机扫描场景改用 VisionKit 的 `VNDocumentCameraViewController`。
10. 人物分割使用 `GeneratePersonSegmentationRequest`，按场景选择 `qualityLevel`：`.accurate`（约 1s，全分辨率）、`.balanced`（约 100ms，960x540）、`.fast`（约 10ms，256x144，适合实时）；结果 `PixelBufferObservation.pixelBuffer` 配合 Core Image 的 `CIFilter.blendWithMask()` 应用蒙版。
11. 实例分割（iOS 18+）使用 `GeneratePersonInstanceMaskRequest`，遍历 `observation.allInstances`，对每个索引调用 `observation.generateMask(for: IndexSet(integer: index))` 得到仅含该人物的 `CVPixelBuffer`；旧版（iOS 17+）用 `VNGeneratePersonInstanceMaskRequest` 配合 `generateMaskedImage(ofInstances:from:croppedToInstancesExtent:)`。
12. 目标跟踪使用有状态的 `TrackObjectRequest`：用初始 `DetectedObjectObservation(boundingBox:)` 初始化，然后对每一帧 `pixelBuffer` 复用同一请求实例调用 `perform(on:)`，读取更新后的 `boundingBox`；现代 `TrackObjectRequest` 没有 `trackingLevel` 或 `qualityLevel`。
13. 旧版跟踪使用 `VNTrackObjectRequest` 并保留一个 `VNSequenceRequestHandler`，把每帧结果作为下一帧的输入 observation 回灌。
14. 其他请求类型按需选用：`ClassifyImageRequest`（场景分类）、`GenerateAttentionBasedSaliencyImageRequest` / `GenerateObjectnessBasedSaliencyImageRequest`（显著性）、`GenerateForegroundInstanceMaskRequest`（前景分割）、`DetectRectanglesRequest`（矩形检测）、`DetectHorizonRequest`（地平线角度）、`DetectHumanBodyPoseRequest` / `DetectHumanBodyPose3DRequest` / `DetectHumanHandPoseRequest` / `DetectAnimalBodyPoseRequest`（姿态）、`DetectFaceCaptureQualityRequest`（人脸拍摄质量 0–1）、`TrackRectangleRequest`、`TrackOpticalFlowRequest`、`DetectTrajectoriesRequest`。
15. Core ML 集成（现代 iOS 18+）：用 `MLModel(contentsOf:)` 加载模型，包装为 `CoreMLModelContainer(model:featureProvider:)`，传给 `CoreMLRequest(model:)` 后 `perform(on:)`；分类模型返回 `ClassificationObservation`（`identifier`、`confidence`），图像输出返回 `PixelBufferObservation`，通用预测器返回 `CoreMLFeatureValueObservation`。
16. Core ML 集成（旧版）：用 `VNCoreMLModel(for:)` 包装模型，创建 `VNCoreMLRequest` 并在 completion handler 中把 `request.results` 转为 `[VNClassificationObservation]`，再用 `VNImageRequestHandler` 执行。
17. VisionKit 实时扫描使用 `DataScannerViewController`：先请求相机权限（`AVCaptureDevice.requestAccess(for: .video)`），检查 `isSupported` 和 `isAvailable`，用 `.text(languages:)` 和 `.barcode(symbologies:)`（`VNBarcodeSymbology` 类型）构造，设置 delegate，在 `present` 完成回调中调用 `try? scanner.startScanning()`。
18. SwiftUI 集成时将 `DataScannerViewController` 包进 `UIViewControllerRepresentable`，在 `updateUIViewController` 中用 `Task { @MainActor in try? controller.startScanning() }` 启动扫描。
19. 所有 Vision 请求放到后台线程或使用 async/await 的 detached task，避免阻塞主线程。
20. 对低质量结果应用 confidence 阈值过滤；文本识别在已知输入语言时设置语言提示。
21. 为 VisionKit 在 Info.plist 中添加 `NSCameraUsageDescription`，并在展示前请求相机权限、展示后再启动扫描。
22. 错误处理覆盖请求失败和空结果两种情况。
23. 审查时逐项核对：是否使用现代 API、是否在非主线程执行、是否转换归一化坐标、是否应用置信度阈值、识别级别是否匹配场景、是否设置语言提示、条码类型是否最小化、是否检查 DataScannerViewController 可用性、是否配置相机权限描述、分割质量是否合适、有状态跟踪请求是否跨帧保留。

适用边界 · 注意事项

• 非 iOS/macOS 平台或不需要端侧计算机视觉能力时。
• 部署目标低于 iOS 18 且无法接受旧版 API 的额外复杂度时（需改用 legacy 模式）。
• 需要服务端大规模模型推理或非 Apple 生态的视觉服务时。