API Chat Completions
L’API de conversation la plus utilisée, entièrement compatible avec l’interface OpenAI Chat Completions.
/v1/chat/completionsCréer une conversation de chatPOST https://hub.lurus.cn/v1/chat/completionsRetour token par token en SSE
Laissez le modèle appeler vos fonctions
Mélangez texte et images en entrée
Température / System Prompt / multi-tours
Paramètres de la requête
Obligatoires
| Paramètre | Type | Description |
|---|---|---|
model | string | Nom du modèle, par ex. deepseek-chat, gpt-4o |
messages | array | Tableau des messages de la conversation, voir le format ci-dessous |
Paramètres optionnels courants
| Paramètre | Type | Valeur par défaut | Description |
|---|---|---|---|
temperature | number | 1.0 | Aléa (0–2). Utilisez 0.1 pour le code/les maths, 0.9 pour l’écriture créative |
max_tokens | integer | — | Nombre maximal de tokens générés. Si non défini, c’est le modèle qui décide |
stream | boolean | false | Sortie en fluxStreamingRéponse en flux : le modèle d'IA renvoie le résultat token par token (au lieu d'attendre la génération complète), ce qui réduit la latence du premier caractère. (SSE), voir Réponse en flux |
top_p | number | 1.0 | Échantillonnage par noyau (nucleus sampling), généralement à ajuster en alternative à temperature |
stop | string/array | — | Arrête la génération lorsque cette chaîne est rencontrée |
n | integer | 1 | Nombre de réponses candidates générées simultanément |
user | string | — | Identifiant de l’utilisateur, utilisé pour les journaux d’audit |
Format des Messages
[
{"role": "system", "content": "你是一位专业的技术顾问。"},
{"role": "user", "content": "什么是 RESTful API？"},
{"role": "assistant", "content": "RESTful API 是…"},
{"role": "user", "content": "能举个例子吗？"}
]| Rôle | Usage |
|---|---|
system | Définit le comportement, le ton et les limites de l’IA. À placer en premier dans le tableau |
user | L’entrée de l’utilisateur |
assistant | La réponse de l’IA. Dans une conversation multi-tours, il faut y inclure les réponses précédentes |
Les définitions complètes des champs du corps de requête (ChatCompletionRequest) et des messages (Message) figurent dans la référence des structures de données.
Exemple de base
Réponse en flux
En définissant stream: true, la réponse est renvoyée token par token via des Server-Sent Events, ce qui convient aux applications de type chat.
Format des données en flux
data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"落"},"index":0}]}
data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"叶"},"index":0}]}
...
data: [DONE]TIP
Le dernier data: [DONE] indique la fin du flux ; à ce moment-là, delta.content est vide.
Function Calling
Laissez l’IA décider quand appeler les fonctions que vous fournissez et renvoyer des paramètres structurés (Tool CallTool CallLorsque, durant son raisonnement, le modèle d'IA décide d'appeler un outil externe (recherche, requête de base de données, etc.) et renvoie des paramètres d'appel structurés.). Cela convient aux scénarios de recherche, d’interrogation de base de données, d’appel d’API externes, etc.
Déroulement
graph LR; A[Votre requête<br/>avec définition des tools] --> B[Le modèle renvoie<br/>finish_reason: tool_calls]; B --> C[Vous exécutez la fonction<br/>résultat renvoyé avec role: tool]; C --> D[Le modèle combine le résultat<br/>et génère la réponse finale]Exemple complet : interroger la météo
Prise en charge par le modèle
Le Function Calling nécessite que le modèle le prenne en charge. Nous recommandons d’utiliser gpt-4o, gpt-4o-mini, claude-3-5-sonnet. La série DeepSeek le prend aussi en charge, mais le format des paramètres présente de légères différences ; pensez à le vérifier lors de vos tests.
Entrée multimodale (Vision)
Certains modèles peuvent comprendre le contenu des images : il suffit de mélanger texte et images dans content.
Modèles prenant en charge la Vision
gpt-4o, gpt-4o-mini, gemini-3-pro-preview, gemini-3-pro-image-preview
Limites de taille des images : les images par URL doivent être accessibles publiquement ; pour le Base64, il est recommandé de ne pas dépasser 5 Mo par image.
Bonnes pratiques
Rédaction du System Prompt
{
"role": "system",
"content": "你是一位专业客服。请用友好简洁的语气回答，每条回复不超过 150 字。如遇无法回答的问题，引导用户联系 support@lurus.cn。"
}Un bon System Prompt comprend : la définition du rôle + les exigences de ton + la limite de longueur + la gestion des cas limites.
Repères de réglage de la température
| Scénario | temperature | Description |
|---|---|---|
| Génération de code, calculs mathématiques | 0.0–0.2 | Forte déterminité, moins d’aléa |
| Questions-réponses, résumé, classification | 0.3–0.6 | Précis tout en gardant une certaine souplesse |
| Écriture créative, brainstorming | 0.7–1.0 | Grande diversité |
| Histoires aléatoires, jeu de rôle | 1.0–1.5 | Très créatif, peut être instable |
Gestion des conversations multi-tours
conversation = [
{"role": "system", "content": "你是一位历史老师。"}
]
def chat(user_input: str) -> str:
conversation.append({"role": "user", "content": user_input})
response = client.chat.completions.create(
model="deepseek-chat",
messages=conversation,
max_tokens=500
)
reply = response.choices[0].message.content
conversation.append({"role": "assistant", "content": reply})
return reply
print(chat("秦始皇是谁？"))
print(chat("他有哪些重要成就？")) # 模型能记住上文的"秦始皇"Gestion de la fenêtre de contexte
La longueur de contexte de chaque modèle est limitée (par ex. deepseek-chat accepte 64K tokens). Lorsqu’une conversation devient trop longue, vous pouvez :
- Tronquer les messages les plus anciens (conserver le system + les N derniers tours)
- Résumer régulièrement l’historique de la conversation pour réduire la consommation de tokens
Gestion des erreurs
Codes de statut courants : 400 format de requête incorrect → vérifiez la structure JSON et les paramètres obligatoires ; 401 clé invalide/expirée ; 403 pas d’accès à ce modèle → contactez l’administrateur ; 429 limite de débit dépassée → réessayez avec un backoff exponentiel ; 500/502 anomalie du modèle en amont → réessayez ou basculez vers un modèle de secours. Les codes d’erreur complets et la stratégie de réessai figurent dans Gestion des erreurs.