開(kāi)發(fā)文檔
歡迎使用TIFA AI API。本文檔將指導(dǎo)您如何接入和使用我們的服務(wù)。TIFA AI提供強(qiáng)大的自然語(yǔ)言處理能力,支持多種場(chǎng)景應(yīng)用。
主要特性
- ? 支持流式輸出,實(shí)時(shí)響應(yīng)
- ? 超長(zhǎng)上下文支持,最大支持200K tokens
- ? 多語(yǔ)言支持,支持中英日韓等10+種語(yǔ)言
- ? 99.9%的服務(wù)可用性保證
- ? 格式控制功能,支持JSON、Markdown等結(jié)構(gòu)化輸出
- ? Few-Shot學(xué)習(xí),通過(guò)示例引導(dǎo)模型輸出
- ? 規(guī)則引擎,精確控制輸出風(fēng)格和內(nèi)容
- ? 避免詞功能,智能過(guò)濾不當(dāng)詞匯,提升輸出質(zhì)量
認(rèn)證方式
所有API請(qǐng)求都需要使用API密鑰進(jìn)行認(rèn)證。您可以在控制臺(tái)獲取API密鑰。
注意事項(xiàng):
- API密鑰具有完整的賬戶(hù)權(quán)限,請(qǐng)勿泄露
- 建議使用環(huán)境變量或配置文件存儲(chǔ)API密鑰
- 定期輪換API密鑰以提升安全性
- 可以為不同應(yīng)用創(chuàng)建不同的API密鑰
API Endpoint
POST https://api.leftnorth.com/v1/chat/completions
請(qǐng)求說(shuō)明:
- 支持HTTPS協(xié)議
- 請(qǐng)求體必須是JSON格式
- 響應(yīng)編碼為UTF-8
- 支持跨域請(qǐng)求(CORS)
對(duì)話(huà)接口
接口地址: https://api.leftnorth.com/v1/chat/completions
請(qǐng)求方式: POST
Content-Type: application/json
對(duì)話(huà)接口支持單輪和多輪對(duì)話(huà),可以通過(guò)調(diào)整不同參數(shù)來(lái)控制AI的行為表現(xiàn)。支持流式輸出和普通輸出兩種模式。
參數(shù)說(shuō)明
| 參數(shù)名 | 類(lèi)型 | 必選 | 說(shuō)明 |
|---|---|---|---|
| model | string | 是 | 模型名,例如"tifa-ultra-v2-20250323" |
| messages | array | 是 | 對(duì)話(huà)歷史,包含role和content字段 |
| temperature | number | 否 | 溫度參數(shù),控制隨機(jī)性,范圍0-2,默認(rèn)0.7 |
| top_p | number | 否 | 核采樣參數(shù),控制多樣性,范圍0-1,默認(rèn)0.95 |
| max_tokens | integer | 否 | 生成文本的最大長(zhǎng)度,默認(rèn)2000 |
| repetition_penalty | number | 否 | 重復(fù)懲罰,范圍1-2,默認(rèn)1.03 |
| rule | string | 否 | 輸出規(guī)則,控制格式、風(fēng)格等 |
| examples | array | 否 | 示例對(duì)話(huà),用于Few-Shot學(xué)習(xí) |
| stream | boolean | 否 | 是否啟用流式輸出,默認(rèn)false |
| extra_body.bad_words | array | 否 | 避免詞列表,包含word(詞匯)和weight(權(quán)重1-999)字段,權(quán)重越高避免程度越強(qiáng) |
返回格式:
{
"id": "chat_12345678",
"object": "chat.completion",
"created": 1679478935,
"model": "tifa-ultra-v2-20250323",
"choices": [{
"message": {
"role": "assistant",
"content": "AI的回復(fù)內(nèi)容"
},
"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": "你好,請(qǐng)介紹一下你自己"
}
],
"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": "你好,請(qǐng)介紹一下你自己"
}
],
"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: '你好,請(qǐng)介紹一下你自己'
}
],
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);
代碼說(shuō)明:
- 示例中包含了基本的錯(cuò)誤處理
- 建議在生產(chǎn)環(huán)境中添加重試機(jī)制
- 可以根據(jù)需要調(diào)整超時(shí)設(shè)置
- stream模式下建議使用異步處理
- 規(guī)則功能可以精確控制輸出格式
- 示例功能適用于Few-Shot學(xué)習(xí)場(chǎng)景
- 避免詞功能可以過(guò)濾不當(dāng)詞匯,權(quán)重越高避免程度越強(qiáng)
高級(jí)功能
格式控制 (rule)
通過(guò) rule 參數(shù)精確控制輸出格式、字?jǐn)?shù)、風(fēng)格等
data = {
"model": "tifa-ultra-v2-20250323",
"messages": [
{"role": "user", "content": "介紹人工智能"}
],
"rule": "格式:分3個(gè)段落\n字?jǐn)?shù):每段100字\n風(fēng)格:專(zhuān)業(yè)但易懂",
"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個(gè)段落\\n字?jǐn)?shù):每段100字\\n風(fēng)格:專(zhuān)業(yè)但易懂",
"temperature": 0.4
}'
Few-Shot 學(xué)習(xí) (examples)
通過(guò)示例讓模型學(xué)習(xí)特定的回答模式
data = {
"model": "tifa-ultra-v2-20250323",
"messages": [
{"role": "user", "content": "評(píng)價(jià)這個(gè)產(chǎn)品"}
],
"examples": [
{"role": "user", "content": "評(píng)價(jià)iPhone"},
{"role": "assistant", "content": "優(yōu)點(diǎn):\\n1. 系統(tǒng)流暢\\n2. 生態(tài)完善\\n\\n缺點(diǎn):\\n1. 價(jià)格較高\(yùn)\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": "評(píng)價(jià)這個(gè)產(chǎn)品"}
],
"examples": [
{"role": "user", "content": "評(píng)價(jià)iPhone"},
{"role": "assistant", "content": "優(yōu)點(diǎn):\\n1. 系統(tǒng)流暢\\n2. 生態(tài)完善\\n\\n缺點(diǎn):\\n1. 價(jià)格較高\(yùn)\n2. 充電速度一般"}
],
"temperature": 0.5
}'
流式輸出 (stream)
實(shí)時(shí)獲取模型生成的內(nèi)容,提升用戶(hù)體驗(yàn)
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: '寫(xiě)一個(gè)故事'}],
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);
// 處理流式數(shù)據(jù)
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': '寫(xiě)一個(gè)故事'}],
'stream': True
},
stream=True
)
for line in response.iter_lines():
if line:
print(line.decode('utf-8'))
避免詞過(guò)濾 (bad_words)
智能過(guò)濾不當(dāng)詞匯,提升輸出質(zhì)量和內(nèi)容安全性
data = {
"model": "tifa-ultra-v2-20250323",
"messages": [
{"role": "user", "content": "評(píng)價(jià)一下這個(gè)產(chǎn)品"}
],
"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": "評(píng)價(jià)一下這個(gè)產(chǎn)品"}
],
"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
}'
權(quán)重說(shuō)明:權(quán)重范圍為1-100,數(shù)值越高避免程度越強(qiáng)。建議:
- 輕微避免:1-5
- 中等避免:6-15
- 強(qiáng)烈避免:16-20
- 完全避免:20+
參數(shù)調(diào)優(yōu)
提供豐富的參數(shù)配置,實(shí)現(xiàn)個(gè)性化的輸出控制。
- temperature: 控制輸出隨機(jī)性 (0-2)
- top_p: 控制輸出多樣性 (0-1)
- max_tokens: 控制輸出長(zhǎng)度
- repetition_penalty: 控制重復(fù)度 (1-2)
?? 這些高級(jí)功能可以組合使用,實(shí)現(xiàn)更精確的輸出控制
錯(cuò)誤處理
常見(jiàn)錯(cuò)誤碼:
| 錯(cuò)誤碼 | 說(shuō)明 | 處理建議 |
|---|---|---|
| 400 | 請(qǐng)求參數(shù)錯(cuò)誤 | 檢查請(qǐng)求格式和參數(shù) |
| 401 | 未授權(quán) | 檢查API密鑰是否正確 |
| 429 | 請(qǐng)求過(guò)于頻繁 | 實(shí)現(xiàn)請(qǐng)求限流 |
| 500 | 服務(wù)器錯(cuò)誤 | 稍后重試或聯(lián)系支持 |
使用限制
為了保證服務(wù)質(zhì)量,API訪(fǎng)問(wèn)有以下限制:
- 每個(gè)API密鑰每分鐘最多60次請(qǐng)求
- 每月總使用量根據(jù)套餐不同有所限制
- 單次請(qǐng)求最大tokens數(shù)為200K
- 并發(fā)請(qǐng)求數(shù)限制為10個(gè)
?? 如需更高配額,請(qǐng)聯(lián)系商務(wù)團(tuán)隊(duì)升級(jí)套餐
最佳實(shí)踐
1. 錯(cuò)誤處理
- 實(shí)現(xiàn)完善的錯(cuò)誤處理機(jī)制
- 對(duì)網(wǎng)絡(luò)錯(cuò)誤進(jìn)行重試
- 設(shè)置合理的超時(shí)時(shí)間
- 記錄詳細(xì)的錯(cuò)誤日志
2. 性能優(yōu)化
- 使用連接池復(fù)用連接
- 啟用gzip壓縮
- 實(shí)現(xiàn)請(qǐng)求緩存
- 采用異步處理方式
3. 安全建議
- 使用環(huán)境變量存儲(chǔ)密鑰
- 啟用HTTPS傳輸
- 實(shí)現(xiàn)請(qǐng)求簽名機(jī)制
- 定期更新API密鑰
4. 開(kāi)發(fā)建議
- 合理使用規(guī)則功能控制輸出
- 利用示例功能提升輸出質(zhì)量
- 做好開(kāi)發(fā)環(huán)境與生產(chǎn)環(huán)境隔離
- 實(shí)現(xiàn)優(yōu)雅的降級(jí)機(jī)制
?? 這些最佳實(shí)踐將幫助您構(gòu)建更穩(wěn)定可靠的應(yīng)用