Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Cuir Citáidí i bhFeidhm i bPython

Ceacht 9 as 16 Nuashonraithe 3 Samhain 2026 Ardleibhéal
Ar an leathanach seo
  1. An Píblíne Citáide Iomlán
  2. Sainigh an Conradh Samhla sa Teachtaireacht Chórais
  3. Dear an Uirlis Chuardaigh
  4. Torthaí a Thabhairt Ar Ais i bhFormáid Tagartha
  5. Téacs a Scaradh ó Thagairtí
  6. Taispeáint Front-end a Ullmhú
  7. Príomhphointí

Nuashonraithe an 3 Samhain, 2026 bunaithe ar threoir Citations & References Mistral: leanann toradh an uirlis an formáid dhoiciméadaithe—frithne innéacsaithe de réir uimhir foinse, gan réimsí type ná reference_id—agus réitítear na reference_ids sa fhreagra trí str(ref_id) laistigh den fhrithne sin. Foinse: Citations & References.

An Píblíne Citáide Iomlán

Cuirfidh tú píblíne RAG le chéile anois a thugann citáidí dá fhoinsí, ón gcéad ghlaon API go dtí an struchtúr sonraí a úsáideann do chomhéadan. Coinnigh an prionsabal seo i gcuimhne: ní fhéachann an tsamhail doiciméid léi féin riamh. Cuireann sí in iúl go bhfuil cuardach uirthi, déanann tú an cuardach sin i do bhunachar sonraí féin, agus ansin tugann tú na blúirí ar ais in éineacht lena n-aitheantóirí. Cruthaíonn an t-idirghníomhaíocht seo freagra ina bhfanann gach maíomh nasctha le doiciméad fíor.

Go sonrach, éilíonn timthriall iomlán dhá ghlaon ar chat.complete. Spreagann an chéad cheann an glaon uirlis; gineann an dara ceann an freagra citáilte nuair a instealltar na foinsí isteach sa stair. Siúlóimid tríd an timthriall seo ag baint úsáide as cás simplí: cúntóir doiciméadaithe inmheánaí a chuirtear faoi cheist faoi dhea-chleachtais chun LLM a imlonnú.

Sainigh an Conradh Samhla sa Teachtaireacht Chórais

Leagann an teachtaireacht chórais an conradh: freagair bunaithe ar na foinsí soláthraithe, déan citáidí go córasach, agus os cionn gach rud, admhaigh nuair atá eolas in easnamh seachas an bhearna a líonadh. Déanann an treoir dheireanach seo an difríocht sa táirgeadh, toisc go mbíonn claonadh ag freagraí dul ar seachrán ar cheisteanna nach bhfuil clúdaithe go maith ag an mbunachar doiciméadaithe.

from mistralai.client import Mistral
import json

client = Mistral(api_key="your-api-key")

# Teachtaireacht chórais a spreagann citáidí
system_message = {
    "role": "system",
    "content": (
        "You are a documentation assistant. "
        "Answer questions using the provided sources. "
        "Cite your sources systematically. "
        "If the information is not in any source, state this explicitly."
    )
}

user_message = {
    "role": "user",
    "content": "What are the best practices for deploying an LLM in production?"
}

messages = [system_message, user_message]

Dear an Uirlis Chuardaigh

Déanann an uirlis cur síos ar conas a bhreathnaíonn cuardach doiciméad i do chóras: anseo, feidhm shimplí search_documentation a ghlacann ceist téacs. Ní bhíonn freagra scríofa ag teastáil ón gcéad ghlaon; tá súil leis go gcruthóidh an tsamhail an cheist a mheasann sí a bheith ábhartha, rud a shábhálann ort sraithe athfhoirmithe a scríobh.

reference_tool = {
    "type": "function",
    "function": {
        "name": "search_documentation",
        "description": "Searches the documentation database",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "Search query"
                }
            },
            "required": ["query"]
        }
    }
}

# An chéad ghlaon: iarrann an tsamhail an uirlis a úsáid
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=[reference_tool]
)

Torthaí a Thabhairt Ar Ais i bhFormáid Tagartha

Is é seo an chéim struchtúrach. Tagann torthaí do innill chuardaigh ar ais i ToolMessage arb é a bhfuil ann ná an frithne tagartha ón gcacht roimhe seo: tá uimhir ("0", "1"…), URL, teideal, agus na blúirí roghnaithe ag gach foinse. Is iad na huimhreacha seo a athúsáideann an tsamhail chun a citáidí a mharcáil, agus a réiteoidh do chuid front-end ina naisc níos déanaí.

from mistralai.client.models import ToolMessage

# Torthaí cuardaigh doiciméadaithe, i bhformáid tagartha Mistral
references = {
    "0": {
        "url": "https://docs.example.com/deployment-guide",
        "title": "LLM Deployment Guide",
        "snippets": [[
            "Always configure rate limits to protect the service.",
            "Monitor P99 latency and error rates continuously."
        ]],
        "description": None,
        "date": "2026-09-01",
        "source": "docs"
    },
    "1": {
        "url": "https://docs.example.com/security",
        "title": "AI Application Security",
        "snippets": [[
            "Filter user inputs to prevent injections.",
            "Never expose API keys on the client side."
        ]],
        "description": None,
        "date": "2026-08-15",
        "source": "docs"
    },
    "2": {
        "url": "https://docs.example.com/scaling",
        "title": "Scalability and Performance",
        "snippets": [[
            "Use semantic caching to reduce API calls.",
            "Size instances based on peak traffic."
        ]],
        "description": None,
        "date": "2026-07-20",
        "source": "docs"
    }
}

# Cuir an glaon uirlis agus an fhreagra leis an stair
tool_call = response.choices[0].message.tool_calls[0]
messages.append(response.choices[0].message)

messages.append(
    ToolMessage(
        tool_call_id=tool_call.id,
        name="search_documentation",
        content=json.dumps(references, ensure_ascii=False)
    )
)

Tabhair faoi deara go ndéantar teachtaireacht bhunaidh na samhla a ath-instealladh isteach sa stair roimh an ToolMessage: gan an péire glaon uirlis / toradh uirlis seo, diúltaíonn an API don leanúnachas. Ní gá na sainmhínithe uirlisí don dara glaon a thuilleadh, ós rud é go bhfuil an cuardach déanta cheana féin.

# An dara glaon: gineann an tsamhail freagra le citáidí
final_response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages
)

Téacs a Scaradh ó Thagairtí

Ní teaghrán simplí a thuilleadh an freagra citáilte ach seicheamh de smutánna ina n-aistríonn siad idir prós agus marcanna citáide. Baineann an pharsáil leis an seicheamh seo a thrasnú agus a shórtáil: athchruthaíonn oibiachtaí TextChunk an téacs inléite, agus soláthraíonn oibiachtaí ReferenceChunk na reference_ids a úsáideadh i ndáiríre. Tugann an t-idirdhealú seo eolas luachmhar duit: go díorthach cé na foinsí a d’úsáid an tsamhail astu siúd a sholáthair tú.

from mistralai.client.models import TextChunk, ReferenceChunk

def parse_cited_response(response):
    """Baintear téacs agus tagairtí as freagra citáilte."""
    content_parts = response.choices[0].message.content
    text_parts = []
    cited_refs = set()

    for chunk in content_parts:
        if isinstance(chunk, TextChunk):
            text_parts.append(chunk.text)
        elif isinstance(chunk, ReferenceChunk):
            for ref_id in chunk.reference_ids:
                cited_refs.add(ref_id)

    return {
        "text": "".join(text_parts),
        "references_used": list(cited_refs)
    }

result = parse_cited_response(final_response)
print("=== Freagra ===")
print(result["text"])
print("\n=== Foinsí Citáilte ===")
for ref_id in result["references_used"]:
    source = references[str(ref_id)]
    print(f"  - {source['title']} : {source['url']}")

Taispeáint Front-end a Ullmhú

Dá ndéanfá an freagra a chothromú go téacs simplí, chaillfeá suíomh na gcitáidí, agus dá bhrí sin a luach. Is fearr an seicheamh a choinneáil agus é a shaibhriú: réitigh gach ReferenceChunk i gcoinne tábla tagartha chun teideal agus URL gach foinse a iompar. Faigheann do chomhéadan liosta ordaithe de bhlocanna ar féidir leo a thaispeáint mar naisc inchliceáilte, leideanna uirlisí, nó uimhreacha citáide idirghníomhacha, gan an téacs a léirmhíniú riamh.

def format_for_frontend(response, reference_map):
    """Formádaíonn sé an freagra le citáidí don front-end."""
    content_parts = response.choices[0].message.content
    formatted = []

    for chunk in content_parts:
        if isinstance(chunk, TextChunk):
            formatted.append({
                "type": "text",
                "content": chunk.text
            })
        elif isinstance(chunk, ReferenceChunk):
            refs = []
            for ref_id in chunk.reference_ids:
                source = reference_map.get(str(ref_id))
                if source:
                    refs.append({
                        "id": ref_id,
                        "title": source["title"],
                        "url": source["url"]
                    })
            formatted.append({
                "type": "citation",
                "references": refs
            })

    return formatted

Sula n-osclaíonn tú an phíblíne seo do do bhunachar doiciméadaithe iomlán, rith é le trí go cúig foinse amháin, mar atá sa sampla thuas. Feicfidh tú láithreach an ndéanann an tsamhail citáidí ag an áit cheart, an n-úsáideann sí doiciméid iolracha, nó an ngreamaíonn sí go córasach den chéad cheann, rud a ligeann duit an teachtaireacht chórais a cheartú sula gcailltear an t-iompar sa toirt.

Príomhphointí

  • Leanann an phíblíne sreabhadh dhá ghlaon: glaon uirlis ansin freagra citáilte
  • Seachadtar tagairtí trí ToolMessage, i bhfrithne innéacsaithe de réir uimhir foinse ("0", "1"…)
  • Tá meascán de TextChunk agus ReferenceChunk sa fhreagra le parsáil
  • Struchtúraigh an t-aschur ionas gur féidir le do front-end citáidí idirghníomhacha a thaispeáint
  • Déan tástáil le 3–5 foinse chun an t-iompar a bhailíochtú sula n-aistríonn tú go dtí an táirgeadh