API Ollama: Khắc phục các Sai lầm Thường gặp

Hiểu về cửa sổ ngữ cảnh 100k

Câu đầu tiên của mỗi phần trả lời câu hỏi trong tiêu đề của phần đó.

Cửa sổ ngữ cảnh 100.000 token nghe có vẻ rất lớn, nhưng nó được chia đều giữa phần đầu vào và phần tạo ra. Khi bạn gửi một phần hướng dẫn hệ thống dài kèm theo lịch sử hội thoại dài, bạn sẽ tiêu thụ ngân sách này nhanh hơn bạn nghĩ. Nhiều nhà phát triển cho rằng giới hạn này chỉ áp dụng cho đầu vào, điều này dẫn đến các phản bị cắt ngắn hoặc lỗi âm thầm khi mô hình đạt đến giới hạn của nó.

Hãy cân nhắc một kịch bản nơi bạn chuyển một tài liệu 50.000 token làm ngữ cảnh. Bạn chỉ còn lại 50.000 token cho phần tạo thực tế. Nếu bạn không quản lý sự cân bằng này cẩn thận, mô hình sẽ ngắt giữa chừng. Luôn theo dõi tổng số token được gửi trong mỗi yêu cầu để tránh cắt xén không mong đợi.

Số token tối đa so với chiều dài đầu ra mặc định

Mỗi phần phải trả lời câu hỏi trong tiêu đề của nó.

Trừ khi bạn chỉ định giới hạn, hầu hết các API mặc định có độ dài đầu ra khiêm tốn, thường vào khoảng 2.048 token. Mặc định này hữu ích cho các truy vấn ngắn nhưng gây tai hại cho việc tạo mã hoặc viết văn dài. Nếu bạn cần mô hình tạo ra một kịch bản đầy đủ hoặc một phân tích chi tiết, bạn phải đặt rõ ràng tham số max_tokens.

Cài đặt giá trị này quá cao cũng có thể ảnh hưởng đến độ trễ và chi phí. Bạn đang trả tiền cho mọi token được tạo ra, dù hữu ích hay không. Cách tiếp cận thực tế là đặt một giới hạn trên hợp lý phù hợp với trường hợp sử dụng của bạn, thay vì để mặc định hoặc một giá trị vô hạn tùy ý.

Xử lý đúng các chunk SSE phát trực tiếp

Streaming yêu cầu xử lý cẩn thận các Server-Sent Events để tránh mất dữ liệu.

Khi bạn bật chế độ streaming, API trả về một chuỗi các khối nhỏ thay vì một phản hồi hoàn chỉnh duy nhất. Mỗi khối chứa một phần văn bản, nhưng các chi tiết quan trọng như thống kê sử dụng token thường chỉ có trong khối cuối cùng. Nếu bạn ngừng phân tích quá sớm, bạn sẽ bỏ lỡ dữ liệu sử dụng cần thiết cho việc tính phí hoặc theo dõi giới hạn tốc độ.

Ngoài ra, streaming đưa ra sự phức tạp trong xử lý lỗi. Một sự cố mạng có thể khiến bạn nhận được văn bản bị ngắt quãng. Bạn cần một trình phân tích mạnh mẽ có thể tái tạo lại thông điệp đầy đủ từ các đoạn văn bản này. Điều này đặc biệt đúng khi tích hợp với các thành phần giao diện người dùng hiển thị văn bản theo thời gian thực.

Lỗi định nghĩa công cụ Function Calling

Gọi hàm thất bại khi các lược đồ công cụ không khớp với kỳ vọng của mô hình.

Mô hình yêu cầu một cấu trúc JSON cụ thể cho các định nghĩa công cụ. Nếu bạn bỏ qua các trường bắt buộc hoặc sử dụng sai kiểu dữ liệu, mô hình có thể bỏ qua hoàn toàn công cụ hoặc trả về phản hồi bị lỗi. Đây là một điểm đau phổ biến đối với các nhà phát triển đang xây dựng các agent cần tương tác với các API bên ngoài.

Luôn xác lược lược đồ công cụ của bạn với tài liệu API trước khi gửi yêu cầu. Ngay cả những sai lệch nhỏ, chẳng hạn như sử dụng số nguyên thay vì chuỗi cho một tham số, cũng có thể làm hỏng lệnh gọi hàm. Việc gỡ lỗi điều này đòi hỏi phải kiểm tra phản hồi JSON thô để xem liệu mô hình có cố gắng gọi công cụ hay không.

Vấn đề định dạng phản hồi Chế độ JSON

Chế độ JSON bắt buộc mô hình xuất ra JSON hợp lệ, nhưng nó vẫn có thể hallucinate.

Khi bạn đặt response_format thành json_object, mô hình bị ràng buộc chỉ xuất ra JSON. Tuy nhiên, điều này không đảm bảo nội dung đúng về mặt ngữ nghĩa. Mô hình có thể tạo ra cú pháp JSON hợp lệ nhưng với các khóa sai hoặc thiếu trường. Bạn vẫn cần một trình phân tích cú pháp để xác minh cấu trúc trước khi sử dụng dữ liệu.

Hơn nữa, chế độ JSON đôi khi có thể làm giảm khả năng sáng tạo hoặc tính linh hoạt của mô hình. Nếu câu lệnh của bạn quá phức tạp, mô hình có thể gặp khó khăn trong việc phù hợp với cấu trúc JSON cứng nhắc. Hãy sử dụng chế độ này chủ yếu cho việc trích xuất dữ liệu có cấu trúc hoặc đối số hàm nơi sự nhất quán quan trọng hơn sắc thái.

Giới hạn tốc độ và yêu cầu đồng thời

Giới hạn tốc độ được thực thi trên mỗi khóa API, không phải trên mỗi người dùng hoặc địa chỉ IP.

Hầu hết các API áp đặt giới hạn về số lượng yêu cầu mỗi phút và kết nối đồng thời. Nếu bạn vượt quá các giới hạn này, bạn sẽ nhận được lỗi 429 Too Many Requests. Điều này rất quan trọng đối với các ứng dụng tạo ra nhiều luồng hoặc quy trình để xử lý yêu cầu của người dùng. Một khóa duy nhất chỉ có thể xử lý một số lượng yêu song song có giới hạn.

Để quản lý điều này, hãy triển khai cơ chế backoff theo cấp số nhân trong mã client của bạn. Khi nhận được lỗi 429, hãy đợi một khoảng thời gian ngắn trước khi thử lại. Điều này ngăn máy chủ bị quá tải và đảm bảo trải nghiệm người dùng mượt mà hơn. Luôn kiểm tra các tiêu đề phản hồi để lấy giá trị retry-after nhằm tối ưu hóa thời gian chờ của bạn.

Hành vi thay thế khóa API

Việc tạo lại khóa API sẽ vô hiệu hóa khóa trước đó ngay lập tức.

Một số nền tảng chỉ cho phép một khóa hoạt động duy nhất cho mỗi tài khoản. Nếu bạn tạo một khóa mới, khóa cũ sẽ ngừng hoạt động ngay lập tức. Điều này có thể gây ra sự cố nếu bạn có nhiều dịch vụ hoặc tập lệnh sử dụng khóa cũ. Luôn cập nhật tất cả các phiên bản khóa của bạn trước khi xoay vòng nó.

Hành vi này được thiết kế cho bảo mật, đảm bảo rằng một khóa bị rò rỉ không thể được sử dụng vô thời hạn. Tuy nhiên, nó đòi hỏi quản lý cẩn thận trong các hệ thống phân tán. Sử dụng biến môi trường hoặc trình quản lý bí mật để lưu trữ khóa của bạn, giúp việc cập nhật dễ dàng hơn và ít lỗi hơn.

Giới hạn kích thước thân yêu cầu

Các tải trọng lớn có thể vượt quá giới hạn thân yêu cầu 8 MB.

Khi gửi các tài liệu dài hoặc hình ảnh được mã hóa dưới dạng base64, thân yêu cầu có thể tăng nhanh. Nếu bạn vượt quá giới hạn kích thước, máy chủ sẽ từ chối yêu cầu với lỗi 413 Payload Too Large. Đây là giới hạn cứng không thể tăng lên bằng cách nâng cấp gói của bạn trong nhiều trường hợp.

Để tránh điều này, hãy nén đầu vào của bạn hoặc chia các tài liệu lớn thành các phần nhỏ hơn. Bạn cũng có thể sử dụng phương pháp mã hóa hiệu quả hơn cho hình ảnh. Luôn theo dõi kích thước các yêu cầu của bạn, đặc biệt khi xử lý nội dung giàu phương tiện.