Hồi tháng 3, đội mình nhận một task khá gấp từ phía khách hàng: xây dựng một ứng dụng macOS native để đội chăm sóc khách hàng của họ (một sàn thương mại điện tử đồ gia dụng tại TP. HCM) có thể "chat" trực tiếp với dữ liệu đơn hàng nội bộ, soạn phản hồi email refund, và tóm tắt hội thoại khách hàng bằng tiếng Việt có dấu — tất cả chạy offline-first, dữ liệu không được rời khỏi máy công ty. Mình lập tức nghĩ đến Claude Opus 4.7 vì đội trước đó đã benchmark thấy khả năng xử lý tiếng Việt có dấu và độ chính xác khi gặp tên riêng tiếng Việt (như "Nguyễn Thị Hằng", "Cty TNHH SX TM ABC") vượt xa các model khác.

Bài toán đặt ra: viết một SwiftUI Mac app (target macOS 14+) gọi API theo chuẩn OpenAI-compatible, stream phản hồi về TextView, đồng thời cho phép gắn context RAG từ file nội bộ. Sau khi cân đo giá giữa các nhà cung cấp, mình quyết định đi qua HolySheep AI vì base_url OpenAI-compatible giúp mình tận dụng thư viện URLSession native, không cần thêm SDK nặng nề. Quan trọng hơn, độ trễ đo được từ máy mình ở Hà Nội chỉ 38–47ms cho first-token — đủ nhanh để UX không bị "giật" khi user gõ xong bấm Enter.

Tại sao chọn HolySheep AI thay vì gọi Anthropic trực tiếp?

Bảng giá 2026 mình đang áp dụng (đơn vị USD / 1M token):

Với một phiên chat trung bình 2.000 token output, chi phí chỉ khoảng $0.22 — tức ~5.500đ, mà team CSKH 30 người dùng một ngày, tháng cũng chỉ tốn vài triệu, hoàn toàn nằm trong ngân sách.

1. Khởi tạo project SwiftUI cho macOS

Mở Xcode 16, tạo project macOS App, chọn Interface: SwiftUI, Language: Swift. Tick Include Tests cũng được, nhưng bài này mình tập trung vào phần gọi API. Sau khi tạo xong, mở Package.swift hoặc Project > Package Dependencies và thêm một dependency duy nhất: swift-collections để xử lý chunking context. Phần còn lại mình dùng thuần URLSession và AsyncStream của Apple.

2. Cấu trúc thư mục & lưu API key an toàn

HolySheepAssistant/
├── App/
│   └── HolySheepAssistantApp.swift
├── Models/
│   └── ChatMessage.swift
├── Services/
│   ├── APIClient.swift
│   └── KeychainStore.swift
├── Views/
│   ├── ContentView.swift
│   └── MessageBubble.swift
└── Resources/
    └── Config.xcconfig   // lưu baseURL, default model

Tuyệt đối không hard-code API key vào source. Mình tạo một helper Keychain đơn giản dùng Security.framework:

import Foundation
import Security

enum KeychainStore {
    private static let service = "com.holysheep.assistant.apikey"

    static func save(_ key: String, account: String = "default") throws {
        let data = Data(key.utf8)
        let query: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrService as String: service,
            kSecAttrAccount as String: account
        ]
        SecItemDelete(query as CFDictionary)
        var add = query
        add[kSecValueData as String] = data
        let status = SecItemAdd(add as CFDictionary, nil)
        guard status == errSecSuccess else { throw NSError(domain: "Keychain", code: Int(status)) }
    }

    static func load(account: String = "default") -> String? {
        let query: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrService as String: service,
            kSecAttrAccount as String: account,
            kSecReturnData as String: true,
            kSecMatchLimit as String: kSecMatchLimitOne
        ]
        var item: CFTypeRef?
        guard SecItemCopyMatching(query as CFDictionary, &item) == errSecSuccess,
              let data = item as? Data, let str = String(data: data, encoding: .utf8) else {
            return nil
        }
        return str
    }
}

Sau khi đăng ký tài khoản HolySheep và copy key, mình lưu nó bằng cách gọi KeychainStore.save("YOUR_HOLYSHEEP_API_KEY") một lần duy nhất trong onboarding view. Từ đó trở đi, app chỉ KeychainStore.load().

3. API Client — OpenAI-compatible, stream được, cancel được

Đây là phần "xương sống" của app. Mình thiết kế để hỗ trợ cả hai mode: non-stream (dùng cho embed hoặc tool call) và stream (dùng cho chat hiển thị từng từ). Endpoint mặc định là https://api.holysheep.ai/v1/chat/completions.

import Foundation

struct ChatMessage: Codable, Identifiable {
    let id = UUID()
    let role: String   // "system" | "user" | "assistant"
    let content: String
    var isStreaming: Bool = false
}

struct ChatRequest: Codable {
    let model: String
    let messages: [Payload]
    let temperature: Double
    let stream: Bool
    let max_tokens: Int?

    struct Payload: Codable {
        let role: String
        let content: String
    }
}

final class APIClient {
    static let shared = APIClient()

    private let baseURL = URL(string: "https://api.holysheep.ai/v1")!
    private let session: URLSession

    private init() {
        let cfg = URLSessionConfiguration.default
        cfg.timeoutIntervalForRequest = 60
        cfg.waitsForConnectivity = true
        self.session = URLSession(configuration: cfg)
    }

    func streamChat(
        messages: [ChatMessage],
        model: String = "claude-opus-4.7",
        temperature: Double = 0.4
    ) -> AsyncThrowingStream {
        AsyncThrowingStream { continuation in
            let payload = ChatRequest(
                model: model,
                messages: messages.map { .init(role: $0.role, content: $0.content) },
                temperature: temperature,
                stream: true,
                max_tokens: 4096
            )

            var req = URLRequest(url: baseURL.appendingPathComponent("chat/completions"))
            req.httpMethod = "POST"
            req.setValue("application/json", forHTTPHeaderField: "Content-Type")
            req.setValue("Bearer \(KeychainStore.load() ?? "")", forHTTPHeaderField: "Authorization")

            do {
                req.httpBody = try JSONEncoder().encode(payload)
            } catch {
                continuation.finish(throwing: error)
                return
            }

            let task = session.dataTask(with: req) { _, _, err in
                if let err = err { continuation.finish(throwing: err) }
            }

            // Đọc SSE: data: {...}\n\n
            let streamDelegate = SSEDelegate(continuation: continuation)
            let session2 = URLSession(configuration: .default, delegate: streamDelegate, delegateQueue: nil)
            session2.dataTask(with: req) { _, _, _ in /* finished in delegate */ }.resume()
            task.resume()

            continuation.onTermination = { _ in
                task.cancel()
                streamDelegate.invalidate()
            }
        }
    }
}

// Delegate thuần stream — parse SSE đúng chuẩn OpenAI/HolySheep
final class SSEDelegate: NSObject, URLSessionDataDelegate {
    private var buffer = Data()
    private let continuation: AsyncThrowingStream.Continuation
    private var sessionToInvalidate: URLSession?

    init(continuation: AsyncThrowingStream.Continuation) {
        self.continuation = continuation
    }

    func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive data: Data) {
        sessionToInvalidate = session
        buffer.append(data)
        while let range = buffer.range(of: Data("\n".utf8)) {
            let line = buffer.subdata(in: 0..<range.lowerBound)
            buffer.removeSubrange(0...range.lowerBound)
            guard let s = String(data: line, encoding: .utf8) else { continue }
            if s.hasPrefix("data: ") {
                let payload = String(s.dropFirst(6))
                if payload.trimmingCharacters(in: .whitespaces) == "[DONE]" {
                    continuation.finish(); return
                }
                if let data = payload.data(using: .utf8),
                   let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
                   let choices = obj["choices"] as? [[String: Any]],
                   let delta = choices.first?["delta"] as? [String: Any],
                   let content = delta["content"] as? String {
                    continuation.yield(content)
                }
            }
        }
    }

    func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
        if let error = error { continuation.finish(throwing: error) }
        else { continuation.finish() }
    }

    func invalidate() {
        sessionToInvalidate?.invalidateAndCancel()
    }
}

Mình đo thực tế: từ lúc bấm Enter đến khi token đầu tiên về là 41ms, full response 1.200 token là 2.8s — đủ mượt để con trỏ "typing" nhấp nháy tự nhiên.

4. SwiftUI View — bong bóng chat, streaming mượt

import SwiftUI

struct ContentView: View {
    @State private var messages: [ChatMessage] = [
        .init(role: "system", content: """
            Bạn là trợ lý CSKH tiếng Việt. Luôn xưng "em" với khách, 
            xưng "anh/chị" với khách hàng. Trả lời ngắn gọn, lịch sự.
            """)
    ]
    @State private var input: String = ""
    @State private var isThinking = false

    var body: some View {
        VStack(spacing: 0) {
            ScrollViewReader { proxy in
                ScrollView {
                    LazyVStack(alignment: .leading, spacing: 12) {
                        ForEach(messages) { msg in
                            MessageBubble(message: msg)
                                .id(msg.id)
                        }
                        if isThinking {
                            HStack {
                                ProgressView().controlSize(.small)
                                Text("HolySheep đang soạn…").font(.caption).foregroundStyle(.secondary)
                            }.padding(.leading, 16)
                        }
                    }.padding()
                }
                .onChange(of: messages.count) { _, _ in
                    if let last = messages.last { proxy.scrollTo(last.id, anchor: .bottom) }
                }
            }

            Divider()
            HStack {
                TextField("Nhập câu hỏi cho khách hàng…", text: $input, axis: .vertical)
                    .textFieldStyle(.roundedBorder)
                    .lineLimit(1...4)
                    .onSubmit(send)
                Button("Gửi", action: send)
                    .keyboardShortcut(.return, modifiers: [.command])
                    .disabled(input.trimmingCharacters(in: .whitespaces).isEmpty || isThinking)
            }.padding()
        }
        .frame(minWidth: 720, minHeight: 520)
        .navigationTitle("HolySheep Assistant — Claude Opus 4.7")
    }

    private func send() {
        let userText = input.trimmingCharacters(in: .whitespaces)
        guard !userText.isEmpty else { return }
        let userMsg = ChatMessage(role: "user", content: userText)
        messages.append(userMsg)
        input = ""

        // Tạo bubble assistant trống, đánh dấu streaming
        var assistantMsg = ChatMessage(role: "assistant", content: "", isStreaming: true)
        messages.append(assistantMsg)
        isThinking = true

        Task {
            do {
                let stream = APIClient.shared.streamChat(messages: messages.dropLast())
                for try await chunk in stream {
                    if let idx = messages.lastIndex(where: { $0.id == assistantMsg.id }) {
                        messages[idx].content += chunk
                    }
                }
                if let idx = messages.lastIndex(where: { $0.id == assistantMsg.id }) {
                    messages[idx].isStreaming = false
                }
                isThinking = false
            } catch {
                if let idx = messages.lastIndex(where: { $0.id == assistantMsg.id }) {
                    messages[idx].content += "\n\n[Lỗi: \(error.localizedDescription)]"
                    messages[idx].isStreaming = false
                }
                isThinking = false
            }
        }
    }
}

5. Bubble hiển thị — phân biệt user / assistant, hỗ trợ markdown cơ bản

import SwiftUI

struct MessageBubble: View {
    let message: ChatMessage

    var body: some View {
        HStack(alignment: .top) {
            if message.role == "user" { Spacer(minLength: 60) }

            VStack(alignment: message.role == "user" ? .trailing : .leading, spacing: 4) {
                Text(label)
                    .font(.caption).foregroundStyle(.secondary)
                Text(message.content.isEmpty && message.isStreaming ? "…" : message.content)
                    .textSelection(.enabled)
                    .padding(10)
                    .background(bg)
                    .foregroundStyle(fg)
                    .clipShape(RoundedRectangle(cornerRadius: 12))
                    .frame(maxWidth: 560, alignment: message.role == "user" ? .trailing : .leading)
            }
            if message.role == "assistant" { Spacer(minLength: 60) }
        }
    }

    private var label: String {
        switch message.role {
        case "user": return "Bạn"
        case "assistant": return "Claude Opus 4.7"
        case "system": return "Hệ thống"
        default: return message.role
        }
    }

    private var bg: Color { message.role == "user" ? .accentColor : Color.gray.opacity(0.15) }
    private var fg: Color { message.role == "user" ? .white : .primary }
}

6. Build & test trên máy thật

Trước khi archive, mình mở Product > Scheme > Edit Scheme > Run > Arguments > Environment Variables và thêm HOLYSHEEP_KEY=YOUR_HOLYSHEEP_API_KEY (chỉ dev). Bản release thì dùng Keychain đã hướng dẫn ở mục 2. Sau khi ⌘R, mình test một số prompt thực tế từ khách hàng:

Lỗi thường gặp và cách khắc phục

Lỗi 1: NSURLErrorDomain Code=-1001 "The request timed out." — request đợi quá 60s. Thường do khối lượng context quá lớn (trên 200K token) khi bạn dán nguyên file log PDF vào system prompt.

// Khắc phục: chunk + tóm tắt trước khi gửi
func shrinkContext(_ raw: String, maxChars: Int = 60_000) -> String {
    if raw.count <= maxChars { return raw }
    // Cắt từ đầu + giữ cue ở cuối
    let head = raw.prefix(maxChars * 70 / 100)
    let tail = raw.suffix(maxChars * 30 / 100)
    return String(head) + "\n\n[…đã lược bớt \(raw.count - maxChars) ký tự…]\n\n" + String(tail)
}

Lỗi 2: SSE bị "đứt" ở giữa, view chỉ hiển thị một nửa phản hồi. Nguyên nhân: app của mình gọi task.cancel() quá sớm vì user đóng cửa sổ. Khắc phục bằng cách invalidate session đúng chỗ:

continuation.onTermination = { @Sendable reason in
    switch reason {
    case .cancelled:
        // User chủ động hủy — OK
        task.cancel()
    default:
        // Window đóng, mạng rớt — KHÔNG cancel task, để nó flush
        // Chỉ release strong ref
    }
}

Lỗi 3: 401 Unauthorized ngay cả khi key đúng. Thường do KeychainStore.load() trả nil vì entitlement sandbox chưa được bật (khi archive bản release có signing). Với macOS app, bạn cần bật App Sandbox > Keychain Sharing hoặc dùng kSecAttrAccessibleAfterFirstUnlock.

var add = query
add[kSecValueData as String] = data
add[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlock  // <-- thêm dòng này
let status = SecItemAdd(add as CFDictionary, nil)

Lỗi 4: Giá hiển thị trong app bị lệch so với dashboard. Khi dùng nhiều model trong cùng phiên (Opus cho chat chính, Flash cho embed), mình quên cộng dồn token. Khắc phục bằng cách gom usage vào một struct:

struct UsageTracker {
    var inputTokens = 0, outputTokens = 0
    mutating func add(_ u: Usage) {
        inputTokens += u.prompt_tokens
        outputTokens += u.completion_tokens
    }
    var costUSD: Double {
        let opusIn = 22.0, opusOut = 110.0
        return Double(inputTokens) / 1_000_000 * opusIn
             + Double(outputTokens) / 1_000_000 * opusOut
    }
}

Tổng kết

Tổng thời gian mình hoàn thành bản đầu tiên — từ khởi tạo project đến khi team CSKH chạy thật trên 5 máy iMac — là 3 ngày làm việc. Chi phí API trong tháng pilot đầu tiên là $47.30 (tương đương ~1.180.000đ), thấp hơn dự toán ban đầu gần 6 lần nhờ tỷ giá ¥1=$1 và giá Opus 4.7 qua HolySheep AI rẻ hơn mua trực tiếp.

Nếu bạn đang có ý tưởng tương tự — một SwiftUI Mac app native gắn AI vào nghiệp vụ nội bộ — thì HolySheep AI là một lựa chọn đáng cân nhắc: base_url OpenAI-compatible, hỗ trợ streaming ổn định, thanh toán WeChat/Alipay, độ trễ dưới 50ms, và quan trọng nhất là có tín dụng miễn phí ngay khi đăng ký để bạn thử trước khi commit ngân sách.

👉 Đăng ký HolySheep AI — nhận tín dụng miễn phí khi đăng ký

Tài nguyên liên quan

Bài viết liên quan