Scéimí JSON agus Bailíochtú
Ar an leathanach seo
Scéimí JSON agus Bailíochtú
Ní píobaireacht bailíochta í scéim feidhme: is é an t-aon chonradh idir an tsamhail agus do chód. Níl aon chainéal eile ann. Ní léann an tsamhail do chur i bhfeidhm, níl a fhios aici do choinbhinsiúin inmheánacha, agus ní thuarfaidh sí go bhfuil súil le formáid ISO i réimse date seachas formáid Fhrancach.
Cinnefidh tuairimí randamacha na samhla aon rud nach bhfuil scríofa sa scéim. Míníonn sé seo an míchothromaíocht iarrachta a mholtar sa cheacht seo: is fearr deich nóiméad a chaitheamh ar scéim ná dhá uair an chloig ag dífhabhtú argóintí neamhchobhsaí.
Struchtúr Scéim Feidhme
Leanann gach feidhm a dheclaraítear i tools formáid Scéim JSON. Seo an struchtúr iomlán:
tool_definition = {
"type": "function",
"name": "creer_facture",
"description": "Create an invoice for an existing customer",
"parameters": {
"type": "object",
"properties": {
"client_id": {
"type": "string",
"description": "Unique customer identifier (format: CLI-XXXXX)"
},
"lignes": {
"type": "array",
"description": "List of billing line items",
"items": {
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "Product or service description"
},
"quantite": {
"type": "integer",
"minimum": 1,
"description": "Number of units"
},
"prix_unitaire": {
"type": "number",
"minimum": 0,
"description": "Unit price excluding tax in euros"
}
},
"required": ["description", "quantite", "prix_unitaire"]
}
},
"devise": {
"type": "string",
"enum": ["EUR", "USD", "GBP"],
"default": "EUR"
},
"echeance_jours": {
"type": "integer",
"enum": [30, 45, 60, 90],
"description": "Payment deadline in days"
}
},
"required": ["client_id", "lignes"],
"additionalProperties": False
},
"strict": True
}
Mód Dian
Tiontaíonn an mód dian dóchúlacht ráthaíocht. Gan é, cruthaíonn an tsamhail argóintí comhlíontacha de ghnáth—agus faigheann tú amach na heisceachtaí sa táirgeadh, ar chásanna imeallacha. Leis, cinntítear comhlíonadh de réir tógála ag leibhéal an díchódaithe. Cumasaigh é mar réamhshocrú: is praghas beag iad na srianta a fhorchuireann sé, atá mionsonraithe díreach thíos, chun rang iomlán fabhtanna a dhíothú.
tools = [{
"type": "function",
"name": "enregistrer_commande",
"description": "Record a new order",
"parameters": {
"type": "object",
"properties": {
"produit": {"type": "string"},
"quantite": {"type": "integer"},
"urgent": {"type": "boolean"}
},
"required": ["produit", "quantite", "urgent"],
"additionalProperties": False
},
"strict": True
}]
Srianta an Mhóid Dhian
Sa mhód dian, táirgtear rialacha áirithe:
- Caithfidh gach réimse a bheith in
required - Caithfidh
additionalPropertiesa bheithfalse - Úsáideann cineálacha roghnacha
anyOflenull - Gan
pattern,minLength, námaxLengthag an leibhéal barr
# Optional field in strict mode
"commentaire": {
"anyOf": [
{"type": "string"},
{"type": "null"}
],
"description": "Optional free-text comment"
}
Bailíochtú ar an gCliant
Ráthaíonn an mód dian foirm, ach ní brí riamh. D’fhéadfadh dáta dea-chumtha a bheith san am atá thart, d’fhéadfadh aitheantóir dea-chlóscríofa gan a bheith ag teacht le haon chustaiméir, agus d’fhéadfadh méid bailí an teorainn údaraithe a shárú. Is loighic gnó iad na rialacha seo: ní chuireann aon scéim JSON in iúl iad, agus ní mór iad a fhíorú i do chód—le, i gcás diúltaithe, teachtaireacht earráide a sheoladh ar ais chuig an tsamhail ag míniú cad a chuaigh mícheart.
import json
from jsonschema import validate, ValidationError
SCHEMA_FACTURE = {
"type": "object",
"properties": {
"client_id": {"type": "string", "pattern": "^CLI-[0-9]{5}$"},
"lignes": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"description": {"type": "string", "minLength": 1},
"quantite": {"type": "integer", "minimum": 1},
"prix_unitaire": {"type": "number", "minimum": 0}
},
"required": ["description", "quantite", "prix_unitaire"]
}
}
},
"required": ["client_id", "lignes"]
}
def executer_fonction(name: str, arguments: str) -> str:
args = json.loads(arguments)
try:
validate(instance=args, schema=SCHEMA_FACTURE)
except ValidationError as e:
return json.dumps({"error": f"Invalid arguments: {e.message}"})
# Business logic after validation
return creer_facture(**args)
Cur Síos Éifeachtach
Scríobh cur síos feidhme mar threoracha do chomhghleacaí nua: cathain a ghlaofar air, agus go háirithe cathain nach ba chóir glaoch air. Is é an dara cuid sin a ndéanaimid dearmad go córasach air, ach réitíonn sé an chuid is mó de na glaonna earráideacha—coscaíonn “ná húsáid le haghaidh orduithe cartlainne” turas gan ghá nach gcuirfeadh trí abairt de chur síos dearfach stop leis.
# Bad: too vague
{
"name": "get_data",
"description": "Retrieve data"
}
# Good: specific and contextual
{
"name": "rechercher_produits_catalogue",
"description": "Search for products in the e-commerce catalog. "
"Returns name, price, stock, and category. "
"Use for questions about availability or pricing."
}
Cur Síos ar Pharaiméadair
Ag leibhéal na bparaiméadar, is é an t-easpa follais an namhaid. Aonad (euró nó ceint?), formáid (ISO nó áitiúil?), coinbhinsiún (Aitheantas inmheánach nó tagairt chustaiméara?) nach scríobhtar, tuarfar iad—uaireanta go ceart, uaireanta nach ea, gan aon chomhartha ar bith ar an mbealach ar bith. Is é an enum do uirlis is fearr anseo: ní dhéanann sé cur síos ar an luach a bhfuil súil leis, srianann sé é.
"properties": {
"date_debut": {
"type": "string",
"description": "Start date in ISO 8601 format (YYYY-MM-DD). "
"Defaults to today's date if not specified."
},
"statut": {
"type": "string",
"enum": ["actif", "inactif", "suspendu"],
"description": "Filter by account status. "
"'actif' = accounts in service, "
"'suspendu' = temporarily frozen accounts."
}
}
Scéimí Neadaithe agus Tagairtí
Tá scéim atá neadaithe go domhain deacair duitse a léamh arís agus don tsamhail í a líonadh go ceart. Má shroicheann tú trí leibhéal, ní hé an cheist le cur ná conas é a scríobh níos fearr, ach an bhfuil an fheidhm ag déanamh an iomarca: is fearr beirt fheidhmeanna le raon feidhme soiléir beagnach i gcónaí ná feidhm inchumraithe amháin a chlúdaíonn an dá chás.
adresse_schema = {
"type": "object",
"properties": {
"rue": {"type": "string"},
"code_postal": {"type": "string"},
"ville": {"type": "string"},
"pays": {"type": "string", "enum": ["FR", "BE", "CH", "LU"]}
},
"required": ["rue", "code_postal", "ville", "pays"]
}
tools = [{
"type": "function",
"name": "creer_livraison",
"description": "Create a delivery with shipping and destination addresses",
"parameters": {
"type": "object",
"properties": {
"expedition": adresse_schema,
"destination": adresse_schema,
"poids_kg": {"type": "number", "minimum": 0.1}
},
"required": ["expedition", "destination", "poids_kg"],
"additionalProperties": False
},
"strict": True
}]
Príomhphointí
- Cumasaigh
strict: truechun comhlíonadh argóintí a ráthú - Déan bailíochtú fós ar an gcliant le
jsonschemale haghaidh rialacha gnó - Scríobh cur síos cruinn: is iad sin an príomhghióga cáilíochta
- Úsáid
enumchun luachanna glactha a shrianadh - Bris scéimeanna casta ina bhfo-struchtúir in-athúsáidte