Dotaz obsluhující koncové body pro vlastní modely
V tomto článku se dozvíte, jak formátovat žádosti o bodování pro obsluhované modely a jak tyto požadavky odeslat do koncového bodu obsluhující model. Pokyny jsou relevantní pro poskytování vlastních modelů, které Databricks definuje jako tradiční modely ML nebo přizpůsobené modely Pythonu zabalené ve formátu MLflow. Můžou být zaregistrované buď v katalogu Unity, nebo v registru modelu pracovního prostoru. Mezi příklady patří modely scikit-learn, XGBoost, PyTorch a Hugging Face Transformer. Další informace o této funkci a podporovaných kategoriích modelů najdete v tématu Model obsluhující s Azure Databricks .
Požadavky na dotazy na úlohy generující AI a LLM najdete v tématu Základní modely dotazů a externí modely.
Požadavky
- Model obsluhující koncový bod
- Pro sadu SDK pro nasazení MLflow se vyžaduje MLflow 2.9 nebo vyšší.
- Žádost o bodování v přijatém formátu
- Pokud chcete odeslat žádost o bodování prostřednictvím rozhraní REST API nebo sady SDK pro nasazení MLflow, musíte mít token rozhraní API Databricks.
Důležité
Jako osvědčený postup zabezpečení pro produkční scénáře doporučuje Databricks používat tokeny OAuth počítače pro ověřování během produkčního prostředí.
Pro účely testování a vývoje doporučuje Databricks místo uživatelů pracovního prostoru používat osobní přístupový token patřící instančním objektům . Pokud chcete vytvořit tokeny pro instanční objekty, přečtěte si téma Správa tokenů instančního objektu.
Dotazování metod a příkladů
Služba rozhraní AI Model Serving poskytuje následující možnosti pro odesílání žádostí o bodování na obsluhované modely:
Metoda | Podrobnosti |
---|---|
Obsluha uživatelského rozhraní | Na stránce Obsluha koncového bodu v pracovním prostoru Databricks vyberte koncový bod dotazu. Vložte vstupní data modelu formátu JSON a klikněte na Odeslat požadavek. Pokud má model zaprotokolovaný vstupní příklad, načtěte ho pomocí příkazu Zobrazit příklad . |
REST API | Volání a dotazování modelu pomocí rozhraní REST API Podrobnosti najdete v tématu POST /serving-endpoints/{name}/invocations . Žádosti o bodování na koncové body obsluhující více modelů najdete v tématu Dotazování jednotlivých modelů za koncovým bodem. |
Sada SDK pro nasazení MLflow | K dotazování modelu použijte funkci predict() sady SDK pro nasazení MLflow. |
Funkce SQL | Vyvolání odvozování modelu přímo z SQL pomocí ai_query funkce SQL Viz Dotaz na model obsluhované pomocí ai_query(). |
Příklad bodování datového rámce Pandas
Následující příklad předpokládá podobný , kde je název vaší instance Databricks a token rozhraní REST API Databricks volaný DATABRICKS_API_TOKEN
.<databricks-instance>
MODEL_VERSION_URI
https://<databricks-instance>/model/iris-classifier/Production/invocations
Viz Podporované formáty bodování.
REST API
Určení skóre modelu, který přijímá rozdělený vstupní formát datového rámce
curl -X POST -u token:$DATABRICKS_API_TOKEN $MODEL_VERSION_URI \
-H 'Content-Type: application/json' \
-d '{"dataframe_split": [{
"columns": ["sepal length (cm)", "sepal width (cm)", "petal length (cm)", "petal width (cm)"],
"data": [[5.1, 3.5, 1.4, 0.2], [4.9, 3.0, 1.4, 0.2]]
}]
}'
Určení skóre modelu, který přijímá vstupy tensoru Vstupy Tensoru by měly být formátované, jak je popsáno v dokumentaci k rozhraní API služby TensorFlow.
curl -X POST -u token:$DATABRICKS_API_TOKEN $MODEL_VERSION_URI \
-H 'Content-Type: application/json' \
-d '{"inputs": [[5.1, 3.5, 1.4, 0.2]]}'
Sada SDK pro nasazení MLflow
Důležité
Následující příklad používá predict()
rozhraní API ze sady SDK pro nasazení MLflow.
import mlflow.deployments
export DATABRICKS_HOST="https://<workspace_host>.databricks.com"
export DATABRICKS_TOKEN="dapi-your-databricks-token"
client = mlflow.deployments.get_deploy_client("databricks")
response = client.predict(
endpoint="test-model-endpoint",
inputs={"dataframe_split": {
"index": [0, 1],
"columns": ["sepal length (cm)", "sepal width (cm)", "petal length (cm)", "petal width (cm)"],
"data": [[5.1, 3.5, 1.4, 0.2], [4.9, 3.0, 1.4, 0.2]]
}
}
)
SQL
Důležité
Následující příklad používá integrovanou funkci SQL ai_query. Tato funkce je ve verzi Public Preview a definice se může změnit. Viz Dotaz na model obsluhované pomocí ai_query().
Následující příklad dotazuje model za sentiment-analysis
koncovým bodem s text
datovou sadou a určuje návratový typ požadavku.
SELECT text, ai_query(
"sentiment-analysis",
text,
returnType => "STRUCT<label:STRING, score:DOUBLE>"
) AS predict
FROM
catalog.schema.customer_reviews
Power BI
Datovou sadu v Power BI Desktopu můžete ohodnocet pomocí následujícího postupu:
Otevřete datovou sadu, kterou chcete skóre.
Přejděte na Transformovat data.
Klikněte pravým tlačítkem na levý panel a vyberte Vytvořit nový dotaz.
Přejděte do zobrazení > Rozšířený editor.
Po vyplnění příslušného
DATABRICKS_API_TOKEN
kódu nahraďte text dotazu následujícím fragmentem kódu aMODEL_VERSION_URI
.(dataset as table ) as table => let call_predict = (dataset as table ) as list => let apiToken = DATABRICKS_API_TOKEN, modelUri = MODEL_VERSION_URI, responseList = Json.Document(Web.Contents(modelUri, [ Headers = [ #"Content-Type" = "application/json", #"Authorization" = Text.Format("Bearer #{0}", {apiToken}) ], Content = {"dataframe_records": Json.FromValue(dataset)} ] )) in responseList, predictionList = List.Combine(List.Transform(Table.Split(dataset, 256), (x) => call_predict(x))), predictionsTable = Table.FromList(predictionList, (x) => {x}, {"Prediction"}), datasetWithPrediction = Table.Join( Table.AddIndexColumn(predictionsTable, "index"), "index", Table.AddIndexColumn(dataset, "index"), "index") in datasetWithPrediction
Pojmenujte dotaz požadovaným názvem modelu.
Otevřete rozšířený editor dotazů pro datovou sadu a použijte funkci modelu.
Příklad vstupu Tensoru
Následující příklad vyhodnocí model, který přijímá vstupy tensoru. Vstupy Tensoru by měly být formátované, jak je popsáno v dokumentaci k rozhraní API služby TensorFlow. V tomto příkladu se předpokládá, že se jedná o název MODEL_VERSION_URI
<databricks-instance>
https://<databricks-instance>/model/iris-classifier/Production/invocations
vaší instance Databricks a token rozhraní REST API Databricks, který se nazývá .DATABRICKS_API_TOKEN
curl -X POST -u token:$DATABRICKS_API_TOKEN $MODEL_VERSION_URI \
-H 'Content-Type: application/json' \
-d '{"inputs": [[5.1, 3.5, 1.4, 0.2]]}'
Podporované formáty bodování
U vlastních modelů podporuje obsluha modelů žádosti o bodování ve vstupním prvku DataFrame nebo Tensoru pandas.
Datový rámec Pandas
Požadavky by se měly odesílat vytvořením datového rámce Pandas serializovaného JSON s jedním z podporovaných klíčů a objektem JSON odpovídajícím vstupnímu formátu.
(Doporučeno)
dataframe_split
formát je datový rámec Pandas serializovaný ve formátu JSON v orientacisplit
.{ "dataframe_split": { "index": [0, 1], "columns": ["sepal length (cm)", "sepal width (cm)", "petal length (cm)", "petal width (cm)"], "data": [[5.1, 3.5, 1.4, 0.2], [4.9, 3.0, 1.4, 0.2]] } }
dataframe_records
je datový rámec Pandas serializovaný ve formátu JSON v orientacirecords
.Poznámka:
Tento formát nezaručuje zachování řazení sloupců a
split
formát je upřednostňovaný před formátemrecords
.{ "dataframe_records": [ { "sepal length (cm)": 5.1, "sepal width (cm)": 3.5, "petal length (cm)": 1.4, "petal width (cm)": 0.2 }, { "sepal length (cm)": 4.9, "sepal width (cm)": 3, "petal length (cm)": 1.4, "petal width (cm)": 0.2 }, { "sepal length (cm)": 4.7, "sepal width (cm)": 3.2, "petal length (cm)": 1.3, "petal width (cm)": 0.2 } ] }
Odpověď z koncového bodu obsahuje výstup z vašeho modelu serializovaného pomocí JSON zabaleného do predictions
klíče.
{
"predictions": [0,1,1,1,0]
}
Vstup Tensoru
Pokud váš model očekává tensory, jako je TensorFlow nebo Pytorch model, existují dvě podporované možnosti formátu pro odesílání požadavků: instances
a inputs
.
Pokud máte více pojmenovaných tensorů na řádek, musíte mít jeden z každého tensoru pro každý řádek.
instances
je formát založený na tensorech, který přijímá tensory ve formátu řádků. Tento formát použijte, pokud mají všechny vstupní tensory stejnou 0-té dimenzi. Koncepčně lze každý tensor v seznamu instancí spojit s ostatními tensory stejného názvu ve zbytku seznamu, aby se vytvořil úplný vstupní tensor modelu, který by byl možný pouze v případě, že by všechny tenzory měly stejnou 0-té dimenzi.{"instances": [ 1, 2, 3 ]}
Následující příklad ukazuje, jak zadat více pojmenovaných tenzorů.
{ "instances": [ { "t1": "a", "t2": [1, 2, 3, 4, 5], "t3": [[1, 2], [3, 4], [5, 6]] }, { "t1": "b", "t2": [6, 7, 8, 9, 10], "t3": [[7, 8], [9, 10], [11, 12]] } ] }
inputs
odesílat dotazy s tensory ve sloupcových formátech. Tento požadavek se liší, protože ve skutečnosti existuje jiný počet instancí tensorut2
(3) nežt1
at3
, takže tento vstup není možné reprezentovat veinstances
formátu.{ "inputs": { "t1": ["a", "b"], "t2": [[1, 2, 3, 4, 5], [6, 7, 8, 9, 10]], "t3": [[[1, 2], [3, 4], [5, 6]], [[7, 8], [9, 10], [11, 12]]] } }
Odpověď z koncového bodu je v následujícím formátu.
{
"predictions": [0,1,1,1,0]
}
Příklad poznámkového bloku
Příklad testování koncového bodu obsluhy modelů pomocí modelu Pythonu najdete v následujícím poznámkovém bloku: