Hướng Dẫn Khắc Phục Sự Cố API Ollama

Hiểu cấu trúc Điểm cuối API Ollama

The ollama endpoint tuân theo một mẫu RESTful nghiêm ngặt mô phỏng cấu trúc API của OpenAI. Bạn tương tác với nó bằng cách gửi các yêu cầu POST đến /v1/chat/completions và truy vấn các mô hình khả dụng qua GET /v1/models. Việc chuẩn hóa này cho phép bạn hoán đổi các mô hình nền tảng mà không cần viết lại mã khách hàng.

Nhiều nhà phát triển cho rằng điểm cuối hỗ trợ nhúng hoặc tạo hình ảnh theo mặc định. Không phải vậy. Dịch vụ được lưu trữ của chúng tôi, ví dụ, chỉ cung cấp các bản hoàn thiện văn bản với một mô hình không kiểm duyệt duy nhất. Luôn kiểm tra GET /v1/models phản hồi để xem chính xác những khả năng nào được hiển thị. Nếu bạn thấy danh sách các mô hình, hãy xác minh ID của chúng trước khi gửi yêu cầu.

Khi sử dụng phiên bản cục bộ, điểm cuối thường chạy trên http://localhost:11434. Đối với các nhà cung cấp đám mây, bạn sẽ sử dụng URL cơ sở tùy chỉnh. Đảm bảo máy khách HTTP của bạn xử lý các tiêu đề đúng cách, đặc biệt là Content-Type: application/json. Một tiêu đề bị thiếu thường gây ra các lỗi im lặng trông giống như lỗi mô hình.

Các yếu tố cấu trúc then chốt:

• model: Chuỗi định danh cho mô hình LLM cụ thể.
• messages: Một mảng các đối tượng nội dung dựa trên vai trò.
• stream: Một cờ boolean kích hoạt Sự kiện gửi qua máy chủ (SSE).

Tại sao các lệnh gọi API ollama của bạn có thể thất bại

Các cuộc gọi API thường thất bại do sai URL cơ sở, khóa hết hạn hoặc tải trọng JSON bị lỗi. Lỗi phổ biến nhất là phản hồi 401 Unauthorized, có nghĩa là khóa API của bạn bị thiếu hoặc không hợp lệ. Một vấn đề thường gặp khác là 404 Not Found, cho biết điểm cuối không hỗ trợ đường dẫn hoặc ID mô hình được yêu cầu.

Kiểm tra kỹ thân yêu cầu của bạn. Nếu bạn gửi một tham số mà điểm cuối không hỗ trợ, chẳng hạn như modalities cho một mô hình chỉ văn bản, máy chủ có thể từ chối yêu cầu. Dịch vụ của chúng tôi, ví dụ, không hỗ trợ đầu vào hình ảnh. Gửi nó sẽ dẫn đến lỗi ngay lập tức.

Thời gian chờ mạng cũng gây ra sự cố. Nếu phiên bản Ollama cục bộ của bạn đang ở trạng thái nhàn rỗi, nó có thể giải phóng mô hình khỏi VRAM. Yêu cầu đầu tiên sau khi khởi động lạnh có thể mất vài giây. Hãy đặt thời gian chờ rộng rãi trong máy khách HTTP của bạn để tránh ngắt kết nối sớm.

Mã lỗi phổ biến:

• 400: Lỗi Yêu cầu Không hợp lệ (JSON không đúng định dạng hoặc tham số không hợp lệ).
• 401: Không ủy quyền (khóa API không hợp lệ hoặc thiếu).
• 429: Quá nhiều Yêu cầu (vượt quá giới hạn tốc độ).
• 500: Lỗi Máy chủ Nội bộ (lỗi tải mô hình).

Cấu hình Đúng các Mô hình ollama Không kiểm duyệt

Các mô hình không kiểm duyệt thường yêu cầu các tham số cụ thể để hoạt động như mong đợi. Sự khác biệt chính nằm ở system lời nhắc. Bạn phải hướng dẫn rõ ràng mô hình vượt qua các lệnh từ chối tiêu chuẩn. Không có lời nhắc hệ thống mạnh mẽ, mô hình có thể quay lại các hành vi an toàn mặc định.

Điểm cuối của chúng tôi sử dụng ID mô hình uncensored. Bạn gửi yêu cầu đến ID này, và máy chủ xử lý việc chọn mô hình nền tảng. Điều này trừu tượng hóa sự phức tạp của việc quản lý các phiên bản mô hình. Bạn không cần biết kiến trúc nền tảng là dựa trên Llama hay Mistral.

Điều chỉnh temperature tham số để kiểm soát sự sáng tạo. Giá trị 0,7 là điểm khởi đầu tốt cho các phản hồi cân bằng. Các giá trị cao hơn làm tăng tính ngẫu nhiên, điều này hữu ích cho việc viết sáng tạo nhưng có thể làm giảm độ chính xác về mặt thực tế. Các giá trị thấp hơn làm cho đầu ra trở nên xác định hơn.

Mẹo cấu hình:

• Sử dụng top_p bên cạnh temperature để kiểm soát tốt hơn.
• Đặt stop chuỗi để ngăn vòng lặp vô hạn.
• Luôn bao gồm một system tin nhắn cho định nghĩa vai trò.

Xử lý phát trực tiếp và giới hạn token

Các phản hồi dạng stream trả dữ liệu dưới dạng các chunk thông qua các sự kiện được máy chủ gửi (SSE). Mỗi chunk chứa một phần hoàn thành từng phần. Bạn phải ghép các chunk này lại để có phản hồi đầy đủ. Dịch vụ của chúng tôi bao gồm các thống kê sử dụng token trong chunk cuối cùng, cho phép bạn theo dõi chi phí theo thời gian thực.

Giới hạn token rất quan trọng đối với các cuộc trò chuyện dài. Điểm cuối của chúng tôi hỗ trợ cửa sổ ngữ cảnh 100.000 token, kết hợp cả prompt và kết hợp hoàn thành. Tuy nhiên, lượng đầu ra tối đa cho mỗi yêu cầu là 16.000 token. Nếu bạn không đặt max_tokens, mặc default là 2.048 token. Điều này có thể làm cắt ngắn các câu trả lời dài một cách không mong đợi.

Khi stream, hãy xử lý các lỗi mạng một cách khéo léo. Nếu kết nối bị ngắt, bạn có thể tiếp tục từ chunk cuối cùng đã nhận được nếu máy chủ hỗ trợ. Nếu không, bạn có thể cần thử lại toàn bộ yêu cầu. Luôn theo dõi các usage field trong chunk cuối cùng để tránh bất ngờ về hóa đơn.

Thực tiễn tốt nhất cho Streaming:

• Phân tích cú pháp các sự kiện SSE chính xác, bỏ qua các dòng trống.
• Tích lũy các phần trong bộ nhớ hoặc bộ đệm.
• Kiểm tra usage object trong chunk cuối cùng để lấy số lượng token.

Lỗi Hóa đơn và Số học Token

Lỗi thanh toán thường bắt nguồn từ việc hiểu sai cách đếm token. Token được tính phí cho cả đầu vào (prompt) và đầu ra (completion). Giá của chúng tôi là $0.15 cho mỗi 1M token đầu vào và $0.50 cho mỗi 1M token đầu ra. Lỗi và từ chối đều miễn phí, giúp giảm chi phí khi gỡ lỗi.

Các bộ token hóa không luôn ánh xạ 1:1 với các ký tự. Một từ đơn lẻ có thể là nhiều token. Nếu bạn ước tính chi phí dựa trên số lượng ký tự, bạn có thể đánh giá thấp hóa đơn. Sử dụng thư viện token hóa đáng tin cậy trong máy khách của bạn để có số đếm chính xác trước khi gửi yêu cầu.

Tín dụng không hết hạn. Nếu bạn nạp bằng crypto, số dư sẽ tồn tại cho đến khi bạn sử dụng. Điều này hữu ích cho các dự án dài hạn. Tuy nhiên, hãy lưu ý rằng mỗi yêu cầu sẽ tiêu tốn token từ số dư của bạn. Nếu số dư của bạn thấp, các yêu cầu tiếp theo có thể sẽ thất bại.

Mẹo thanh toán:

• Theo dõi mức sử dụng token trong mọi phản hồi.
• Thiết lập cảnh báo cho các ngưỡng số dư thấp.
• Sử dụng max_tokens để giới hạn chi phí tiềm năng.

Vấn đề bảo mật và quét cổng

Các điểm cuối API Ollama cục bộ thường được công khai trên mạng theo mặc định. Điều này khiến chúng dễ bị các trình quét cổng tìm kiếm tài nguyên tính toán miễn phí. Nếu bạn công khai cổng 11434 mà không có xác thực, bất kỳ ai cũng có thể sử dụng tài nguyên GPU của bạn. Điều này có thể dẫn đến hóa đơn tiền điện cao và hiệu suất chậm.

Bảo vệ điểm cuối của bạn bằng cách thay đổi cổng mặc định hoặc sử dụng proxy ngược có xác thực. Dịch vụ lưu trữ của chúng tôi xử lý bảo mật cho bạn, vì vậy bạn không cần phải lo lắng về việc mở cổng. Bạn chỉ cần giữ cho khóa API của mình được bảo mật.

Đối với các thiết lập cục bộ, hãy sử dụng tường lửa để hạn chế quyền truy cập vào các địa chỉ IP đáng tin cậy. Bạn cũng có thể bật xác thực dựa trên token trong tệp cấu hình của Ollama. Điều này ngăn người dùng không được ủy quyền thực hiện các yêu cầu.

Các bước bảo mật:

• Thay đổi cổng mặc định nếu hiển thị ra internet.
• Sử dụng proxy ngược với HTTPS và xác thực.
• Theo dõi lưu lượng mạng của bạn để tìm các hoạt động bất thường.

Sử dụng API ollama Cục bộ so với Đám mây

Sử dụng cục bộ cho bạn quyền kiểm soát đầy đủ đối với quyền riêng tư dữ liệu và lựa chọn mô hình. Bạn có thể chạy nhiều mô hình cùng lúc và chuyển đổi giữa chúng ngay lập tức. Tuy nhiên, bạn chịu trách nhiệm bảo trì phần cứng, cập nhật và bảo mật. Sử dụng đám mây chuyển giao những trách nhiệm này cho nhà cung cấp.

Dịch vụ đám mây của chúng tôi cung cấp một mô hình uncensored được tối ưu hóa cho việc tạo nội dung không giới hạn. Bạn có quyền truy cập ngay lập tức mà không cần tải xuống các tệp mô hình lớn. Điểm hạn chế là dữ liệu của bạn sẽ đi qua máy chủ của chúng tôi. Đối với dữ liệu nhạy cảm, việc chạy cục bộ có thể là lựa chọn tốt hơn.

Các dịch vụ đám mây thường có độ trễ cao hơn do các lần truyền mạng. Các phiên bản cục bộ có độ trễ gần bằng không nếu GPU đủ nhanh. Tuy nhiên, các phiên bản cục bộ yêu cầu VRAM đáng kể. Nếu GPU của bạn hết bộ nhớ, mô hình có thể chuyển sang CPU, làm chậm đáng kể thời gian phản hồi.

So sánh:

• Cục bộ: Quyền riêng tư, kiểm soát, phụ thuộc phần cứng.
• Đám mây: Sự tiện lợi, khả năng mở rộng và chuyển dữ liệu.

Những lỗi phổ biến phía máy khách

Nhà phát triển thường quên xử lý giới hạn tốc độ. Dịch vụ của chúng tôi cho phép 300 yêu cầu mỗi phút trên mỗi khóa. Nếu bạn vượt quá giới hạn này, bạn sẽ nhận được lỗi 429. Hãy triển khai cơ chế backoff theo cấp số nhân trong máy khách của bạn để xử lý các lỗi này một cách mượt mà.

Một sai lầm khác là không đặt stream tham số chính xác. Nếu bạn mong đợi phát trực tiếp nhưng không đặt stream: true, bạn sẽ phải đợi toàn bộ phản hồi trước khi nhận được bất kỳ dữ liệu nào. Điều này có thể làm cho ứng dụng của bạn cảm thấy chậm.

Các lỗi chế độ JSON cũng thường xảy ra. Nếu bạn đặt response_format: {type: "json_object"}, mô hình phải trả về JSON hợp lệ. Nếu không, trình phân tích cú pháp của bạn sẽ bị lỗi. Thêm xử lý lỗi để bắt và thử lại các lỗi phân tích cú pháp JSON.

Danh sách kiểm tra:

• Triển khai xử lý giới hạn tốc độ.
• Đặt stream: true cho các cập nhật theo thời gian thực.
• Xác thực đầu ra JSON khi sử dụng chế độ JSON.