learner.h

前往此文件的文档。

#ifndef XGBOOST_LEARNER_H_
#define XGBOOST_LEARNER_H_

#include <dmlc/io.h> // 用于 Serializable
#include <xgboost/base.h> // 用于 bst_feature_t, bst_target_t, bst_float, Args, GradientPair, ..
#include <xgboost/context.h> // 用于 Context
#include <xgboost/linalg.h> // 用于 Tensor, TensorView
#include <xgboost/metric.h> // 用于 Metric
#include <xgboost/model.h> // 用于 Configurable, Model
#include <xgboost/span.h> // 用于 Span
#include <xgboost/task.h> // 用于 ObjInfo

#include <algorithm> // 用于 max
#include <cstdint> // 用于 int32_t, uint32_t, uint8_t
#include <map> // 用于 map
#include <memory> // 用于 shared_ptr, unique_ptr
#include <string> // 用于 string
#include <utility> // 用于 move
#include <vector> // 用于 vector

namespace xgboost {
class FeatureMap;
class Metric;
class GradientBooster;
class ObjFunction;
class DMatrix;
class Json;
struct XGBAPIThreadLocalEntry;
template <typename T>
class HostDeviceVector;

enum class PredictionType : std::uint8_t { // NOLINT
 kValue = 0,
 kMargin = 1,
 kContribution = 2,
 kApproxContribution = 3,
 kInteraction = 4,
 kApproxInteraction = 5,
 kLeaf = 6
};

class Learner : public Model, public Configurable, public dmlc::Serializable {
 public
 ~Learner() override;
 virtual void Configure() = 0;
 virtual void UpdateOneIter(std::int32_t iter, std::shared_ptr<DMatrix> train) = 0;
 virtual void BoostOneIter(std::int32_t iter, std::shared_ptr<DMatrix> train,
 linalg::Matrix<GradientPair>* in_gpair) = 0;
 virtual std::string EvalOneIter(int iter,
 const std::vector<std::shared_ptr<DMatrix>>& data_sets,
 const std::vector<std::string>& data_names) = 0;
 virtual void Predict(std::shared_ptr<DMatrix> data, bool output_margin,
 HostDeviceVector<bst_float>* out_preds, bst_layer_t layer_begin,
 bst_layer_t layer_end, bool training = false, bool pred_leaf = false,
 bool pred_contribs = false, bool approx_contribs = false,
 bool pred_interactions = false) = 0;

 virtual void InplacePredict(std::shared_ptr<DMatrix> p_m, PredictionType type, float missing,
 HostDeviceVector<float>** out_preds, bst_layer_t layer_begin,
 bst_layer_t layer_end) = 0;

 virtual void CalcFeatureScore(std::string const& importance_type,
 common::Span<int32_t const> trees,
 std::vector<bst_feature_t>* features,
 std::vector<float>* scores) = 0;

 /*
 * \brief 获取梯度提升器中提升的轮数。
 */
 virtual int32_t BoostedRounds() const = 0;
 virtual std::uint32_t Groups() const = 0;

 void LoadModel(Json const& in) override = 0;
 void SaveModel(Json* out) const override = 0;

 virtual void LoadModel(dmlc::Stream* fi) = 0;
 virtual void SaveModel(dmlc::Stream* fo) const = 0;

 virtual void SetParams(Args const& args) = 0;
 virtual void SetParam(const std::string& key, const std::string& value) = 0;

 virtual uint32_t GetNumFeature() const = 0;

 virtual void SetAttr(const std::string& key, const std::string& value) = 0;
 virtual bool GetAttr(const std::string& key, std::string* out) const = 0;
 virtual bool DelAttr(const std::string& key) = 0;
 virtual std::vector<std::string> GetAttrNames() const = 0;
 virtual void SetFeatureNames(std::vector<std::string> const& fn) = 0;
 virtual void GetFeatureNames(std::vector<std::string>* fn) const = 0;
 virtual void SetFeatureTypes(std::vector<std::string> const& ft) = 0;
 virtual void GetFeatureTypes(std::vector<std::string>* ft) const = 0;

 virtual Learner* Slice(bst_layer_t begin, bst_layer_t end, bst_layer_t step,
 bool* out_of_bound) = 0;
 virtual std::vector<std::string> DumpModel(const FeatureMap& fmap,
 bool with_stats,
 std::string format) = 0;

 virtual XGBAPIThreadLocalEntry& GetThreadLocal() const = 0;
 virtual void Reset() = 0;
 static Learner* Create(const std::vector<std::shared_ptr<DMatrix> >& cache_data);
 virtual Context const* Ctx() const = 0;
 virtual const std::map<std::string, std::string>& GetConfigurationArguments() const = 0;

 protected
 std::unique_ptr<ObjFunction> obj_;
 std::unique_ptr<GradientBooster> gbm_;
 std::vector<std::unique_ptr<Metric> > metrics_;
 Context ctx_;
};

struct LearnerModelParamLegacy;

enum class MultiStrategy : std::int32_t {
 kOneOutputPerTree = 0,
 kMultiOutputTree = 1,
};

struct LearnerModelParam {
 private
 linalg::Tensor<float, 1> base_score_;

 public
 bst_feature_t num_feature{0};
 std::uint32_t num_output_group{0};
 ObjInfo task{ObjInfo::kRegression};
 MultiStrategy multi_strategy{MultiStrategy::kOneOutputPerTree};

 LearnerModelParam() = default;
 // 由于旧的 \`LearnerModelParamLegacy\` 仍被二进制 I/O 使用，我们保留
 // 此项作为不可变副本。
 LearnerModelParam(Context const* ctx, LearnerModelParamLegacy const& user_param,
 linalg::Tensor<float, 1> base_margin, ObjInfo t, MultiStrategy multi_strategy);
 LearnerModelParam(LearnerModelParamLegacy const& user_param, ObjInfo t,
 MultiStrategy multi_strategy);
 LearnerModelParam(bst_feature_t n_features, linalg::Tensor<float, 1> base_score,
 std::uint32_t n_groups, bst_target_t n_targets, MultiStrategy multi_strategy)
 : base_score_{std::move(base_score)},
 num_feature{n_features},
 num_output_group{std::max(n_groups, n_targets)},
 multi_strategy{multi_strategy} {}

 linalg::TensorView<float const, 1> BaseScore(Context const* ctx) const;
 [[nodiscard]] linalg::TensorView<float const, 1> BaseScore(DeviceOrd device) const;

 void Copy(LearnerModelParam const& that);
 [[nodiscard]] bool IsVectorLeaf() const noexcept {
 return multi_strategy == MultiStrategy::kMultiOutputTree;
 }
 [[nodiscard]] bst_target_t OutputLength() const noexcept { return this->num_output_group; }
 [[nodiscard]] bst_target_t LeafLength() const noexcept {
 return this->IsVectorLeaf() ? this->OutputLength() : 1;
 }

 /* \brief 此参数是否使用 LearnerModelParamLegacy 初始化。*/
 [[nodiscard]] bool Initialized() const { return num_feature != 0 && num_output_group != 0; }
};

} // 命名空间 xgboost
#endif // XGBOOST_LEARNER_H_