開發文檔
歡迎使用TIFA AI API。本文檔將指導您如何接入和使用我們的服務。TIFA AI提供強大的自然語言處理能力,支持多種場景應用。
當前版本:v1.0
最后更新:2024-03-20
主要特性
- ? 支持流式輸出,實時響應
- ? 超長上下文支持,最大支持200K tokens
- ? 多語言支持,支持中英日韓等10+種語言
- ? 99.9%的服務可用性保證
- ? 格式控制功能,支持JSON、Markdown等結構化輸出
- ? Few-Shot學習,通過示例引導模型輸出
- ? 規則引擎,精確控制輸出風格和內容
- ? 避免詞功能,智能過濾不當詞匯,提升輸出質量
認證方式
所有API請求都需要使用API密鑰進行認證。您可以在控制臺獲取API密鑰。
?? 請妥善保管您的API密鑰,不要在客戶端代碼中明文存儲。
注意事項:
- API密鑰具有完整的賬戶權限,請勿泄露
- 建議使用環境變量或配置文件存儲API密鑰
- 定期輪換API密鑰以提升安全性
- 可以為不同應用創建不同的API密鑰
API Endpoint
POST https://api.leftnorth.com/v1/chat/completions
請求說明:
- 支持HTTPS協議
- 請求體必須是JSON格式
- 響應編碼為UTF-8
- 支持跨域請求(CORS)
對話接口
接口地址: https://api.leftnorth.com/v1/chat/completions
請求方式: POST
Content-Type: application/json
對話接口支持單輪和多輪對話,可以通過調整不同參數來控制AI的行為表現。支持流式輸出和普通輸出兩種模式。
參數說明
| 參數名 | 類型 | 必選 | 說明 |
|---|---|---|---|
| model | string | 是 | 模型名,例如"tifa-ultra-v2-20250323" |
| messages | array | 是 | 對話歷史,包含role和content字段 |
| temperature | number | 否 | 溫度參數,控制隨機性,范圍0-2,默認0.7 |
| top_p | number | 否 | 核采樣參數,控制多樣性,范圍0-1,默認0.95 |
| max_tokens | integer | 否 | 生成文本的最大長度,默認2000 |
| repetition_penalty | number | 否 | 重復懲罰,范圍1-2,默認1.03 |
| rule | string | 否 | 輸出規則,控制格式、風格等 |
| examples | array | 否 | 示例對話,用于Few-Shot學習 |
| stream | boolean | 否 | 是否啟用流式輸出,默認false |
| extra_body.bad_words | array | 否 | 避免詞列表,包含word(詞匯)和weight(權重1-999)字段,權重越高避免程度越強 |
返回格式:
{
"id": "chat_12345678",
"object": "chat.completion",
"created": 1679478935,
"model": "tifa-ultra-v2-20250323",
"choices": [{
"message": {
"role": "assistant",
"content": "AI的回復內容"
},
"finish_reason": "stop",
"index": 0
}],
"usage": {
"prompt_tokens": 56,
"completion_tokens": 31,
"total_tokens": 87
}
}
示例代碼
curl -X POST "https://api.leftnorth.com/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "tifa-ultra-v2-20250323",
"messages": [
{
"role": "user",
"content": "你好,請介紹一下你自己"
}
],
"temperature": 0.7,
"max_tokens": 1000,
"extra_body": {
"bad_words": [
{"word": "牛逼", "weight": 7.0},
{"word": "666", "weight": 8.0},
{"word": "yyds", "weight": 9.0}
]
}
}'
import requests
import json
url = "https://api.leftnorth.com/v1/chat/completions"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_KEY"
}
data = {
"model": "tifa-ultra-v2-20250323",
"messages": [
{
"role": "user",
"content": "你好,請介紹一下你自己"
}
],
"temperature": 0.7,
"max_tokens": 1000,
"extra_body": {
"bad_words": [
{"word": "牛逼", "weight": 7.0},
{"word": "666", "weight": 8.0},
{"word": "yyds", "weight": 9.0}
]
}
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)
const response = await fetch('https://api.leftnorth.com/v1/chat/completions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
},
body: JSON.stringify({
model: 'tifa-ultra-v2-20250323',
messages: [
{
role: 'user',
content: '你好,請介紹一下你自己'
}
],
temperature: 0.7,
max_tokens: 1000,
extra_body: {
bad_words: [
{word: "牛逼", weight: 7.0},
{word: "666", weight: 8.0},
{word: "yyds", weight: 9.0}
]
}
})
});
const result = await response.json();
console.log(result);
代碼說明:
- 示例中包含了基本的錯誤處理
- 建議在生產環境中添加重試機制
- 可以根據需要調整超時設置
- stream模式下建議使用異步處理
- 規則功能可以精確控制輸出格式
- 示例功能適用于Few-Shot學習場景
- 避免詞功能可以過濾不當詞匯,權重越高避免程度越強
高級功能
格式控制 (rule)
通過 rule 參數精確控制輸出格式、字數、風格等
data = {
"model": "tifa-ultra-v2-20250323",
"messages": [
{"role": "user", "content": "介紹人工智能"}
],
"rule": "格式:分3個段落\n字數:每段100字\n風格:專業但易懂",
"temperature": 0.4
}
curl -X POST "https://api.leftnorth.com/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "tifa-ultra-v2-20250323",
"messages": [
{"role": "user", "content": "介紹人工智能"}
],
"rule": "格式:分3個段落\\n字數:每段100字\\n風格:專業但易懂",
"temperature": 0.4
}'
Few-Shot 學習 (examples)
通過示例讓模型學習特定的回答模式
data = {
"model": "tifa-ultra-v2-20250323",
"messages": [
{"role": "user", "content": "評價這個產品"}
],
"examples": [
{"role": "user", "content": "評價iPhone"},
{"role": "assistant", "content": "優點:\\n1. 系統流暢\\n2. 生態完善\\n\\n缺點:\\n1. 價格較高\\n2. 充電速度一般"}
],
"temperature": 0.5
}
curl -X POST "https://api.leftnorth.com/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "tifa-ultra-v2-20250323",
"messages": [
{"role": "user", "content": "評價這個產品"}
],
"examples": [
{"role": "user", "content": "評價iPhone"},
{"role": "assistant", "content": "優點:\\n1. 系統流暢\\n2. 生態完善\\n\\n缺點:\\n1. 價格較高\\n2. 充電速度一般"}
],
"temperature": 0.5
}'
流式輸出 (stream)
實時獲取模型生成的內容,提升用戶體驗
const response = await fetch('/v1/chat/completions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
},
body: JSON.stringify({
model: 'tifa-ultra-v2-20250323',
messages: [{role: 'user', content: '寫一個故事'}],
stream: true
})
});
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
const chunk = decoder.decode(value);
// 處理流式數據
console.log(chunk);
}
import requests
response = requests.post(
'https://api.leftnorth.com/v1/chat/completions',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={
'model': 'tifa-ultra-v2-20250323',
'messages': [{'role': 'user', 'content': '寫一個故事'}],
'stream': True
},
stream=True
)
for line in response.iter_lines():
if line:
print(line.decode('utf-8'))
避免詞過濾 (bad_words)
智能過濾不當詞匯,提升輸出質量和內容安全性
data = {
"model": "tifa-ultra-v2-20250323",
"messages": [
{"role": "user", "content": "評價一下這個產品"}
],
"extra_body": {
"bad_words": [
{"word": "牛逼", "weight": 7.0},
{"word": "666", "weight": 8.0},
{"word": "yyds", "weight": 9.0},
{"word": "絕絕子", "weight": 20.0}
]
},
"temperature": 0.7
}
curl -X POST "https://api.leftnorth.com/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "tifa-ultra-v2-20250323",
"messages": [
{"role": "user", "content": "評價一下這個產品"}
],
"extra_body": {
"bad_words": [
{"word": "牛逼", "weight": 7.0},
{"word": "666", "weight": 8.0},
{"word": "yyds", "weight": 9.0},
{"word": "絕絕子", "weight": 20.0}
]
},
"temperature": 0.7
}'
權重說明:權重范圍為1-100,數值越高避免程度越強。建議:
- 輕微避免:1-5
- 中等避免:6-15
- 強烈避免:16-20
- 完全避免:20+
參數調優
提供豐富的參數配置,實現個性化的輸出控制。
- temperature: 控制輸出隨機性 (0-2)
- top_p: 控制輸出多樣性 (0-1)
- max_tokens: 控制輸出長度
- repetition_penalty: 控制重復度 (1-2)
?? 這些高級功能可以組合使用,實現更精確的輸出控制
錯誤處理
常見錯誤碼:
| 錯誤碼 | 說明 | 處理建議 |
|---|---|---|
| 400 | 請求參數錯誤 | 檢查請求格式和參數 |
| 401 | 未授權 | 檢查API密鑰是否正確 |
| 429 | 請求過于頻繁 | 實現請求限流 |
| 500 | 服務器錯誤 | 稍后重試或聯系支持 |
使用限制
為了保證服務質量,API訪問有以下限制:
- 每個API密鑰每分鐘最多60次請求
- 每月總使用量根據套餐不同有所限制
- 單次請求最大tokens數為200K
- 并發請求數限制為10個
?? 如需更高配額,請聯系商務團隊升級套餐
最佳實踐
1. 錯誤處理
- 實現完善的錯誤處理機制
- 對網絡錯誤進行重試
- 設置合理的超時時間
- 記錄詳細的錯誤日志
2. 性能優化
- 使用連接池復用連接
- 啟用gzip壓縮
- 實現請求緩存
- 采用異步處理方式
3. 安全建議
- 使用環境變量存儲密鑰
- 啟用HTTPS傳輸
- 實現請求簽名機制
- 定期更新API密鑰
4. 開發建議
- 合理使用規則功能控制輸出
- 利用示例功能提升輸出質量
- 做好開發環境與生產環境隔離
- 實現優雅的降級機制
?? 這些最佳實踐將幫助您構建更穩定可靠的應用