API và khóa API

Với API của Genie, ứng dụng và script của bạn có thể đặt câu hỏi cho Genie, tìm trong kho tri thức và thêm tài liệu. Mỗi ứng dụng xác thực bằng một khóa API do chủ sở hữu workspace tạo trong Cài đặt. Bài này hướng dẫn cách tạo khóa, giải thích khóa được và không được truy cập những gì, kèm một ví dụ hoàn chỉnh: đặt câu hỏi, nhận câu trả lời dạng luồng (streaming) và đọc trích dẫn.

Tạo khóa API

Bạn cần vai trò Chủ sở hữu: chỉ chủ sở hữu mới thấy trang API.

1. Mở Cài đặt → API (trong nhóm Phát hành & tích hợp).
2. Trong mục Khóa API, bấm Tạo khóa API.
3. Ở ô Tên, nhập tên cho biết ứng dụng nào dùng khóa, ví dụ Cổng intranet.
4. Ở Loại truy cập, giữ Truy cập theo phạm vi.
5. Ở Quyền, chỉ chọn những gì ứng dụng cần (xem bảng bên dưới). Khóa mới có sẵn các quyền Truy xuất kho tri thức, Trò chuyện và Đọc agent.
6. Ở Kho tri thức, chọn các kho tri thức khóa được dùng, ví dụ Nhân sự. Để trống nếu muốn cho phép mọi kho tri thức trong workspace.
7. Bấm Tạo khóa API.
8. Trong danh sách, bấm nút sao chép ở dòng của khóa và lưu khóa vào kho bí mật của ứng dụng. Khóa luôn bắt đầu bằng sk-.

Ảnh chụp màn hình sẽ được bổ sungCài đặt → API: nơi tạo khóa API của workspacewebsite-docs/public/screenshots/vi/api-keys.png

Cài đặt → API: nơi tạo khóa API của workspace

Để đổi tên, quyền hay kho tri thức của khóa, bấm nút sửa ở dòng của khóa (Sửa khóa API). Thay đổi có hiệu lực ngay và giá trị khóa vẫn giữ nguyên. Để thu hồi khóa, bấm Xóa: mọi tích hợp đang dùng khóa sẽ ngừng hoạt động ngay lập tức.

Chọn quyền

Quyền	Khóa được làm gì
Truy xuất kho tri thức	Tìm và đọc trong các kho tri thức đã chọn. Không trò chuyện hay sửa gì được.
Trò chuyện	Tạo hội thoại của riêng khóa, đặt câu hỏi và xem danh sách agent.
Đọc agent	Xem danh sách agent, chi tiết và câu hỏi gợi ý của từng agent.
Ghi nội dung kho tri thức	Tải tài liệu lên và sửa nội dung trong các kho tri thức đã chọn. Không tạo mới hay xóa sạch được kho tri thức.
Lịch sử tin nhắn	Tìm trong các hội thoại trước đây của chính khóa (khi có định danh người dùng thì là hội thoại của người đó). Không bao giờ chạm tới hội thoại của người khác.

Các quyền còn lại (quản lý kho tri thức, agent, dịch vụ MCP, nguồn dữ liệu, mô hình, kênh, thành viên và cài đặt workspace) cùng Toàn quyền workspace dành cho công cụ quản trị. Chỉ cấp các quyền này cho ứng dụng đáng tin cậy chạy trên máy chủ. Toàn quyền workspace bỏ qua danh sách kho tri thức.

Khóa được và không được truy cập gì

• Kho tri thức: chỉ những kho đã chọn cho khóa. Genie từ chối yêu cầu chỉ định kho khác; khi Genie hay một agent tự chọn kho tri thức, các kho được chọn vẫn chỉ nằm trong danh sách của khóa.
• Tài liệu: chỉ tài liệu không bị giới hạn. Genie không bao giờ tìm hay trích dẫn tài liệu đã được phân quyền cho khóa API, dù khóa có quyền gì, kể cả Toàn quyền workspace.
• Cơ sở dữ liệu và Power BI: không dùng được. Genie trả lời câu hỏi qua API dựa trên tài liệu và, nếu được phép, trên web.
• Chạy mã: Genie không chạy mã trong sandbox cho khóa API.
• Tính năng chỉ dành cho người đã đăng nhập: chia sẻ và xuất hội thoại, phân tích, quản lý khóa API.

Khóa API đại diện cho một ứng dụng, không phải một nhân viên. Gửi kèm ID người dùng (xem Phân biệt người dùng) giúp tách riêng hội thoại của từng người, nhưng không cấp cho khóa quyền xem tài liệu theo phân quyền của người đó. Hội thoại do khóa tạo thuộc về khóa đó: quản trị viên workspace không đọc được trong Genie.

URL gốc

Ô URL gốc của API trên trang API cho biết địa chỉ cần gọi, ví dụ https://genie.contoso.test/api/v1. Mọi yêu cầu đều gửi khóa trong header X-API-Key. Yêu cầu và phản hồi dùng JSON; câu trả lời được gửi dần dưới dạng server-sent events.

Muốn thử gọi API mà không cần viết mã, hãy bấm Mở Playground ở mục API Playground trên cùng trang. Playground dùng một khóa API trong danh sách để tạo hội thoại và gửi câu hỏi thử.

Ví dụ: đặt câu hỏi và nhận câu trả lời dạng luồng

Ví dụ này dùng một khóa có quyền Trò chuyện để hỏi Genie (trợ lý mặc định) về chính sách nghỉ phép của Contoso.

1. Khai báo URL gốc và khóa của bạn:

   GENIE_API=https://genie.contoso.test/api/v1
   GENIE_API_KEY=sk-...   # khóa bạn đã sao chép

2. Tạo một hội thoại:

   curl -s -X POST "$GENIE_API/sessions" \
     -H "X-API-Key: $GENIE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"title":"Annual leave"}'

   Phản hồi chứa ID hội thoại trong data.id:

   {"success":true,"data":{"id":"8b6f2c1e-4d0a-4c55-9a51-2f3e7d9c0b12","title":"Annual leave"}}

   Phản hồi thực tế có nhiều trường hơn; bạn chỉ cần data.id.

3. Đặt câu hỏi trong hội thoại đó:

   SESSION_ID=8b6f2c1e-4d0a-4c55-9a51-2f3e7d9c0b12
   curl -N -X POST "$GENIE_API/agent-chat/$SESSION_ID" \
     -H "X-API-Key: $GENIE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"query":"How many days of annual leave does a new employee get?","agent_id":"builtin-auto","agent_enabled":true,"channel":"api"}'

   builtin-auto là Genie, trợ lý mặc định: Genie tự chọn kho tri thức và công cụ như trên ứng dụng web. Muốn hỏi một agent cụ thể, hãy thay bằng ID của agent đó; gọi GET $GENIE_API/agents để lấy danh sách agent kèm ID. Tùy chọn -N giúp curl in câu trả lời ngay khi nhận được.

4. Đọc luồng phản hồi. Mỗi sự kiện gồm một dòng event:message, tiếp theo là một dòng data: chứa một đối tượng JSON (ví dụ dưới đây đã rút gọn):

   event:message
   data:{"response_type":"agent_query","content":"","done":false,"session_id":"8b6f2c1e-…","assistant_message_id":"c41d9e07-…"}
   
   event:message
   data:{"response_type":"answer","content":"A new employee gets 12 days of annual leave a year","done":false}
   
   event:message
   data:{"response_type":"answer","content":" <kb doc=\"Employee handbook\" chunk_id=\"5a1c…\" kb_id=\"3d7f…\" />.","done":false}
   
   event:message
   data:{"response_type":"references","content":"","done":false,"knowledge_references":[{"id":"5a1c…","knowledge_title":"Employee handbook","knowledge_id":"9e2b…","knowledge_base_id":"3d7f…","content":"Employees receive 12 days of paid annual leave per year…","score":0.82}]}
   
   event:message
   data:{"response_type":"complete","content":"","done":true}

Đọc câu trả lời và trích dẫn

Xử lý từng sự kiện theo response_type:

response_type	Nội dung	Cách xử lý
agent_query	session_id và assistant_message_id	Lưu lại ID tin nhắn nếu bạn có thể cần dừng câu trả lời.
answer	Phần tiếp theo của câu trả lời, trong content	Nối vào câu trả lời theo đúng thứ tự.
references	knowledge_references: các đoạn mà câu trả lời trích dẫn	Hiển thị làm nguồn tham khảo.
error	Lý do câu trả lời thất bại, trong content	Báo lỗi.
complete	Kết thúc câu trả lời (done là true)	Dừng đọc.
thinking, tool_call, tool_result và các loại khác	Các bước làm việc của Genie	Không bắt buộc: bỏ qua nếu bạn chỉ cần câu trả lời.

Trích dẫn nằm ngay trong câu trả lời, dưới dạng thẻ:

• <kb doc="…" chunk_id="…" kb_id="…" /> trích dẫn một đoạn của tài liệu. doc là tên tài liệu; chunk_id trùng với id của một mục trong knowledge_references; mục đó có content là đoạn được trích và knowledge_title là tên tài liệu.
• <web url="…" title="…" /> trích dẫn một trang web.

Trong ứng dụng của bạn, hãy chuyển các thẻ này thành liên kết hoặc chú thích, hoặc bỏ đi nếu chỉ hiển thị văn bản thuần.

Để hỏi tiếp, hãy gửi thêm một yêu cầu agent-chat với cùng ID hội thoại. Muốn đọc lại toàn bộ hội thoại sau này, gọi GET $GENIE_API/messages/$SESSION_ID/load: mỗi câu trả lời có content và knowledge_references.

Phân biệt người dùng (tùy chọn)

Nếu ứng dụng phục vụ nhiều nhân viên bằng cùng một khóa, hãy cho Genie biết ai đang hỏi để hội thoại của mỗi người được tách riêng. Trên trang API, ở mục Chế độ định danh người dùng:

• Chỉ workspace (mặc định): mọi lời gọi dùng chung một danh tính.
• ID người dùng trực tiếp: gửi ID của người dùng trong header X-External-User-ID. Chỉ dùng khi gọi từ máy chủ của bạn, không bao giờ từ trình duyệt.
• Token đã ký: máy chủ của bạn dùng HMAC secret để ký một token ngắn hạn (JWT HS256) cho người dùng và gửi trong header X-External-User-Token. Dùng chế độ này cho ứng dụng mà người dùng tự chạy.

Trên trang đó, bạn sẽ thấy sẵn ví dụ ký token và ví dụ yêu cầu cho chế độ đã chọn.

Lưu ý

• Không bao giờ đặt khóa API trong trang web, ứng dụng di động hay kho mã công khai. Muốn đưa Genie lên một trang web, hãy dùng tiện ích website.
• Các lỗi thường gặp: 401 là thiếu khóa, sai khóa hoặc khóa đã bị xóa; 403 là khóa không có quyền hoặc không được dùng kho tri thức đó; 409 là hội thoại đó vẫn đang có câu trả lời chưa xong; 429 là workspace đã dùng hết hạn mức chi phí tháng.
• Để dừng một câu trả lời, gọi POST $GENIE_API/sessions/$SESSION_ID/stop với {"message_id":"<assistant_message_id>"}.
• Muốn chỉ lấy các đoạn phù hợp mà không cần câu trả lời, ví dụ cho trang tìm kiếm của riêng bạn, dùng POST $GENIE_API/knowledge-search với khóa có quyền Truy xuất kho tri thức.
• Bộ tài liệu này không gồm tài liệu tham chiếu đầy đủ về các endpoint. Hãy liên hệ nhà cung cấp Genie để nhận.

Trang liên quan

• Tổng quan tích hợp
• Tiện ích website
• Phân quyền tài liệu
• Mức sử dụng, phân tích và nhật ký kiểm toán
• Mạng và chống virus