Cách lấy Khóa API Jev (TypeSafe AI)?

Jev là mô hình quyết định của TypeSafe AI. Bạn gửi cho nó một phần trạng thái và một bộ câu hỏi được định kiểu, và nó sẽ trả lời bằng xác suất thay vì văn xuôi. Hướng dẫn này bao gồm khóa API Jev và yêu cầu đầu tiên của bạn; để biết bối cảnh về Jev là gì và tại sao nó trả về các con số thay vì văn bản, hãy đọc Jev là gì trước. Để làm rõ, vì kết quả tìm kiếm khá lộn xộn: đây là Jev - mô hình AI của TypeSafe, không phải FaZe Jev - YouTuber và cũng không phải vắc-xin JEV.

Khóa API Jev hoạt động giống như bất kỳ mã thông báo bearer nào khác, vì vậy nếu bạn mới làm quen với mẫu này, khóa API là gì sẽ trình bày những điều cơ bản. Quyền truy cập API trực tiếp đang trong giai đoạn truy cập sớm, vì vậy bước đầu tiên là thoát khỏi danh sách chờ. Sau đó, bạn sẽ tạo khóa, tìm hiểu hình dạng yêu cầu, gọi điểm cuối bằng curl và Python SDK, đọc các trường xác suất và kết nối yêu cầu vào Apidog với các xác nhận về những xác suất đó. Nếu bạn không thể chờ đợi, cùng một mô hình có sẵn trên Vercel AI Gateway mà không cần danh sách chờ; FAQ đề cập đến lộ trình đó.

Bước 1: Nhận quyền truy cập sớm, sau đó tạo khóa

Jev hiện đang ở giai đoạn truy cập sớm. Bài đăng ra mắt của TypeSafe cho biết họ đang "đưa các nhà phát triển ra khỏi danh sách chờ nhanh nhất có thể", vì vậy hãy tham gia danh sách chờ trên typesafe.ai và đợi lời mời vào console; hiện chưa có đăng ký tự phục vụ. Khi tài khoản console của bạn đã hoạt động, hãy truy cập console.typesafe.ai/settings/keys và tạo một khóa. Sao chép nó một lần và coi nó như một mật khẩu.

Xuất nó dưới dạng biến môi trường thay vì dán vào mã:

export TYPESAFE_API_KEY="ts_..."

Cả ví dụ curl chính thức và Python SDK đều đọc TYPESAFE_API_KEY từ môi trường, vì vậy một biến có thể dùng cho mọi ví dụ bên dưới. Nếu một khóa nào đó lọt vào một commit, hãy xoay vòng nó trong console và chạy kiểm tra rò rỉ khóa API trên toàn bộ kho lưu trữ.

Bước 2: Hiểu hình dạng yêu cầu

Mọi lệnh gọi Jev là một lệnh POST https://api.typesafe.ai/v1/systemone duy nhất với ba trường trong phần thân, được ghi lại trong tài liệu tham khảo API TypeSafe:

Mỗi câu hỏi là một trong ba loại nguyên thủy:

Phản hồi cũng chứa model và usage.input_tokens / usage.output_tokens. Các câu hỏi thuộc các loại khác nhau có thể chia sẻ một trạng thái và trả về trong một lượt đi khứ hồi.

Bước 3: Thực hiện yêu cầu đầu tiên với curl

Yêu cầu này chạy cả ba loại nguyên thủy trên một phiếu hỗ trợ:

curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "My card was charged twice for one order and nobody has replied in three days.",
    "questions": {
      "needs_review": {
        "type": "noul",
        "instructions": "Does this ticket need a human agent?",
        "criteria": {
          "true": "money, legal, or an unanswered complaint",
          "false": "a routine question a bot can close"
        }
      },
      "route": {
        "type": "choice",
        "instructions": "Route this ticket to a team.",
        "criteria": {
          "billing": "payment or charge problems",
          "shipping": "delivery problems",
          "technical": "application bugs"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this ticket?",
        "criteria": ["low", "medium", "high"]
      }
    }
  }'

Một phản hồi trông như thế này (các giá trị mang tính minh họa):

{
  "model": "jev-1.13.0",
  "answers": {
    "needs_review": { "type": "noul", "noul": 0.97 },
    "route": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.98,
      "probabilities": { "billing": 0.98, "shipping": 0.01, "technical": 0.01 }
    },
    "urgency": {
      "type": "score",
      "score": 1.6,
      "confidence": 0.62,
      "legend": { "0": "low", "1": "medium", "2": "high" },
      "probabilities": { "0": 0.02, "1": 0.36, "2": 0.62 }
    }
  },
  "usage": { "input_tokens": 190, "output_tokens": 0 }
}

Bước 4: Đọc các trường xác suất

Đọc các con số một cách chính xác:

• noul là xác suất "có". 0.97 có nghĩa là Jev chắc chắn 97% rằng ticket này cần một người.
• choice là tùy chọn có xác suất cao nhất, probabilities liệt kê mọi tùy chọn, và confidence cho bạn biết mức độ quyết đoán của lựa chọn. Một tuyến đường 0.98 an toàn để tự động hóa; một tuyến đường 0.51 với 0.47 ở vị trí thứ hai là một quyết định may rủi.
• score là vị trí được tính trọng số xác suất trên các cấp độ được sắp xếp, vì vậy 1.6 nằm giữa "medium" (1) và "high" (2). legend ánh xạ từng chỉ mục trở lại nhãn của nó, và probabilities hiển thị toàn bộ phân bố.

Vì đầu ra là một phân phối, không phải một nhãn, bạn đặt ngưỡng, không phải mô hình. Đó là lý do tại sao các xác nhận trong Bước 6 kiểm tra các con số.

Bước 5: Lệnh gọi tương tự với Python SDK

Cài đặt SDK; client sẽ lấy TYPESAFE_API_KEY từ môi trường:

pip install typesafe-sdk

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state="My card was charged twice for one order and nobody has replied in three days.",
        questions={
            "needs_review": Noul(
                instructions="Does this ticket need a human agent?",
                criteria={"true": "money, legal, or an unanswered complaint",
                          "false": "a routine question a bot can close"},
            ),
            "route": Choice(
                instructions="Route this ticket to a team.",
                criteria={"billing": "payment or charge problems",
                          "shipping": "delivery problems",
                          "technical": "application bugs"},
            ),
            "urgency": Score(
                instructions="How urgent is this ticket?",
                criteria=["low", "medium", "high"],
            ),
        },
    )

print(response.nouls["needs_review"].noul)
print(response.choices["route"].choice, response.choices["route"].probabilities)
print(response.scores["urgency"].score)

Các câu trả lời được nhóm theo loại trên đối tượng phản hồi (nouls, choices, scores). Có một JavaScript SDK với hình dạng tương tự, và nếu bạn đã sử dụng Vercel AI Gateway, experimental_evaluate từ AI SDK 7 sẽ gọi mô hình là typesafe-ai/jev, với một điểm khác biệt: loại câu hỏi boolean trả về trường probability thay vì noul.

Bước 6: Lưu trữ và kiểm tra khóa API Jev trong Apidog

Curl chứng minh khóa hoạt động một lần. Apidog giúp yêu cầu có thể chạy lại, xác nhận và tạo mock cho toàn bộ nhóm.

Lưu trữ khóa dưới dạng biến bí mật. Tạo một môi trường có tên TypeSafe và thêm TYPESAFE_API_KEY dưới dạng bí mật để giá trị của nó được ẩn trong giao diện người dùng và không bị xuất ra; Môi trường và biến bí mật của Apidog sẽ hướng dẫn thiết lập. Đặt xác thực trên yêu cầu thành Bearer Token với {{TYPESAFE_API_KEY}} làm giá trị.

Xây dựng yêu cầu POST. Thêm một POST vào https://api.typesafe.ai/v1/systemone, dán phần thân JSON từ Bước 3, và gửi nó đi. Bảng phản hồi sẽ hiển thị cây câu trả lời, vì vậy bạn có thể kiểm tra các xác suất trước khi viết một xác nhận.

Xác nhận trên các xác suất, không phải trên văn xuôi. Trong trình xây dựng xác nhận trực quan, chỉ định các biểu thức JSONPath vào các trường bạn quan tâm:

• $.answers.needs_review.noul lớn hơn 0.9
• $.answers.route.choice bằng billing
• $.answers.route.probabilities.billing lớn hơn 0.8
• $.answers.urgency.score lớn hơn hoặc bằng 1
• $.usage.input_tokens nhỏ hơn 1000

Nếu bạn thích script, bộ xử lý hậu kỳ chấp nhận API pm quen thuộc:

const body = pm.response.json();
pm.test("ticket flagged for a human", () => {
  pm.expect(body.answers.needs_review.noul).to.be.above(0.9);
});
pm.test("routed to billing", () => {
  pm.expect(body.answers.route.choice).to.eql("billing");
});

Lưu nó dưới dạng kịch bản kiểm thử. Đặt yêu cầu vào một kịch bản kiểm thử với một CSV nhỏ chứa các ticket và tuyến đường mong đợi, sau đó chạy nó mỗi khi có thay đổi đối với hướng dẫn hoặc tiêu chí của bạn. Chỉnh sửa lời nhắc là thay đổi mã; một kịch bản mười dòng sẽ phát hiện chỉnh sửa làm giảm lặng lẽ 0.95 xuống còn 0.6. Kịch bản tương tự chạy trong CI thông qua Apidog CLI, vì vậy một lỗi hồi quy sẽ chặn việc hợp nhất.

Mock hình dạng phản hồi đã khai báo. Xác định lược đồ phản hồi trên điểm cuối (ba đối tượng trả lời cộng với usage), và mock thông minh của Apidog sẽ ngay lập tức cung cấp các xác suất giả thực tế. Frontend có thể xây dựng huy hiệu "cần xem xét" và giao diện người dùng định tuyến dựa trên mock trước khi backend được triển khai, sau đó thay đổi URL mock bằng điểm cuối thực tế chỉ với một thay đổi môi trường.

Về việc lên kế hoạch chỗ ngồi: Gói Free của Apidog bao gồm 4 người dùng, và các gói trả phí tính theo từng chỗ ngồi.

Ngưỡng trong mã

Khi các xác nhận đã vượt qua, các con số tương tự sẽ thúc đẩy logic sản xuất. Giữ các ngưỡng ở một nơi và đặt tên cho chúng:

REVIEW_THRESHOLD = 0.9
AUTO_ROUTE_CONFIDENCE = 0.85

needs_review = response.nouls["needs_review"].noul >= REVIEW_THRESHOLD
route = response.choices["route"]

if route.confidence >= AUTO_ROUTE_CONFIDENCE and not needs_review:
    assign(ticket, team=route.choice)
else:
    queue_for_human(ticket, suggested=route.choice)

Ghi lại toàn bộ map probabilities với mỗi quyết định để bạn có thể điều chỉnh ngưỡng từ dữ liệu thực tế sau này, và đặt đánh giá của con người làm mặc định khi độ tin cậy thấp; mô hình đang nói với bạn rằng nó không chắc chắn.

Giới hạn, giá cả và mô hình

Trực tiếp từ trang mô hình của TypeSafe:

Với mức giá đó, một triệu ticket ngắn sẽ có chi phí dưới $10. TypeSafe cũng tuyên bố rằng Jev không được đào tạo trên các yêu cầu hoặc phản hồi của khách hàng.

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

Lỗi 422 là lỗi bạn sẽ gặp nhiều nhất trong quá trình lặp lại; lược đồ điểm cuối từ Bước 6 sẽ bắt hầu hết chúng trước khi yêu cầu rời khỏi máy của bạn.

Câu hỏi thường gặp

Có gói miễn phí cho API Jev không? Các tài liệu công khai liệt kê giá theo token và không mô tả gói miễn phí hoặc tín dụng khởi đầu, và bản thân quyền truy cập hiện đang trong danh sách chờ. Kiểm tra console sau khi lời mời của bạn đến để biết ưu đãi hiện tại, và coi bất kỳ con số nào bạn thấy ở nơi khác là không chính thức.

Tôi có thể nhận được nhiều câu trả lời từ một yêu cầu không? Có. questions là một map, vì vậy một noul, một choice và một score đều có thể chạy trên một trạng thái trong một lệnh gọi duy nhất. Nó rẻ hơn ba yêu cầu và giữ cho các câu trả lời nhất quán vì chúng chia sẻ một đầu vào.

Điều này khác với các đầu ra có cấu trúc trên mô hình chat như thế nào? Đầu ra có cấu trúc buộc một mô hình ngôn ngữ phải phát ra JSON hợp lệ, nhưng các giá trị bên trong vẫn là các token được tạo ra, và trường "confidence" là văn bản mà mô hình tự viết về mình. Jev trả về các xác suất đo lường như là đầu ra gốc, đó là lý do tại sao bạn có thể xác nhận noul > 0.9 và tin tưởng vào phép so sánh.

Tôi có cần SDK của TypeSafe nếu tôi đang dùng Vercel không? Không. Vercel AI SDK hiển thị Jev thông qua experimental_evaluate với typesafe-ai/jev làm ID mô hình. Bạn sẽ xác thực bằng khóa AI Gateway thay vì khóa TypeSafe, và câu trả lời boolean sẽ trả về dưới dạng probability.

Các bước tiếp theo

Bây giờ bạn đã có khóa API Jev, một yêu cầu hoạt động trong curl và Python, và hiểu rõ về noul, choice và score. Đặt yêu cầu vào Apidog, thêm các xác nhận xác suất và lưu kịch bản kiểm thử để các chỉnh sửa lời nhắc được kiểm tra như mã. Tải xuống Apidog để làm theo.